Mon CLAUDE.MD

Sans cadre, Claude Code repart de zéro à chaque session : il oublie ce qui a marché, refait les mêmes erreurs et livre sans vérifier. Ce fichier de contexte, affiné après deux ans d'usage intensif, lui donne une mémoire, un workflow fixe et des règles de code. Voici la plus grande partie, prête à copier.

À quoi sert ce fichier

C'est l'un des fichiers qui ont le plus de valeur chez moi aujourd'hui. Il me permet des développements structurés qui tiennent dans le temps. L'idée tient en quatre blocs.

• Un démarrage cadré : Claude relit ses fichiers de mémoire (leçons, playbook, état courant) avant de toucher au code.
• Un workflow fixe : planifier d'abord, vérifier par la preuve, exiger l'élégance, corriger les bugs jusqu'à la cause racine.
• Des règles de code : la taille des fichiers en trois paliers, des patterns de découpe, la simplicité avant tout.
• Une mémoire durable : quatre fichiers dans tasks/ (todo, leçons, playbook, historique). L'historique n'est jamais chargé par défaut.

Comment l'utiliser

Colle le bloc ci-dessous dans le CLAUDE.md de ton projet, ou dans ton CLAUDE.md global. Garde les sections qui te parlent, enlève le reste, adapte les chemins à ta stack. Une section de trop ne casse rien, une section manquante ne manque à personne.

Le fichier, en grande partie

Copie ce bloc tel quel. Les règles de démarrage, le workflow complet et les principes fondamentaux y sont en entier. Les sections qui suivent (livrables, gestion des tâches, mémoire et clôture) t'attendent complètes dans le fichier.

## DÉMARRAGE DE SESSION
1. Lire tasks/lessons.md : appliquer toutes les leçons avant de toucher quoi que ce soit
2. Lire tasks/playbook.md : réappliquer les pratiques qui ont fait leurs preuves
3. Lire tasks/todo.md : comprendre l'état actuel
4. Si l'un d'eux n'existe pas, le créer avant de commencer
5. NE PAS lire tasks/history.md au démarrage (voir règle plus bas)

## WORKFLOW

### 1. Planifier d'abord
- Passer en mode plan pour toute tâche non triviale (3+ étapes)
- Écrire le plan dans tasks/todo.md avant d'implémenter
- Si quelque chose ne va pas, STOP et re-planifier, ne jamais forcer

### 2. Stratégie sous-agents
- Utiliser des sous-agents pour garder le contexte principal propre
- Une tâche par sous-agent
- Investir plus de compute sur les problèmes difficiles

### 3. Boucle d'auto-amélioration
- Après toute correction : mettre à jour tasks/lessons.md
- Format : [date] | ce qui a mal tourné | règle pour l'éviter
- Après toute réussite nette (pattern qui a bien marché) : mettre à jour tasks/playbook.md
- Format : [date] | pratique | bénéfice court
- Relire lessons.md ET playbook.md à chaque démarrage de session

### 4. Standard de vérification
- Ne jamais marquer comme terminé sans preuve que ça fonctionne
- Lancer les tests, vérifier les logs, comparer le comportement
- Se demander : « Est-ce qu'un staff engineer validerait ça ? »

### 5. Exiger l'élégance
- Pour les changements non triviaux : existe-t-il une solution plus élégante ?
- Si un fix semble bricolé : le reconstruire proprement
- Ne pas sur-ingénieriser les choses simples

### 6. Correction de bugs autonome
- Quand on reçoit un bug : le corriger directement
- Aller dans les logs, trouver la cause racine, résoudre
- Pas besoin d'être guidé étape par étape

### 7. Taille des fichiers : règle des 3 paliers
Un fichier court se lit d'un coup, se merge sans conflit et force à découper la logique proprement.
- Cible : <= 300 lignes. Zone confort, aucun effort de factorisation requis
- Plafond mou : 400 lignes. Signal d'alerte : avant d'ajouter, regarder si on peut extraire un sous-composant, un hook custom, un helper dans src/lib/
- Plafond dur : 500 lignes. Interdit sauf justification explicite documentée en haut du fichier
- Exceptions (hors règle) : migrations SQL, fichiers de config, constants/types/enums, fichiers générés
- Patterns de découpe React quand on dépasse 300 lignes :
  1. Extraire les sous-composants visuels qui ont leur propre state local
  2. Extraire la logique de fetch + state machine dans un hook custom useXxx
  3. Extraire les handlers complexes dans des callbacks nommés (puis dans lib/)
  4. Si toujours > 400 après ça, splitter en pages/sections

## PRINCIPES FONDAMENTAUX
- Simplicité d'abord : toucher un minimum de code
- Pas de paresse : causes racines uniquement, pas de fixes temporaires
- Ne jamais supposer : vérifier chemins, APIs, variables avant utilisation
- Demander une seule fois : une question en amont si nécessaire, ne jamais interrompre en cours de tâche

## LIVRABLES / TEMPLATES
Quand on demande un template destiné à être copié-collé ailleurs (HTML email, snippet, JSON, SQL) :
- Fournir le code DIRECTEMENT dans un bloc copy-pasteable
  [la suite dans le fichier : pas de wireframe ASCII, résumé court, règles email]

## GESTION DES TÂCHES
1. Planifier -> tasks/todo.md
  [les 4 étapes suivantes dans le fichier : vérifier, suivre, expliquer, apprendre]

## MÉMOIRE & CLÔTURE DE SESSION
Les quatre fichiers de mémoire (tasks/) : todo, lessons, playbook, history.
  [dans le fichier : le rôle de chacun, pourquoi history.md ne se charge jamais en entier,
   et comment clôturer une session avec /checkpoint]

## APPRENTISSAGES
(Claude remplit cette section au fil du temps)

Ce que le fichier complet ajoute

La version à télécharger est propre, sans coupe, prête à coller d'un bloc. Elle détaille les trois sections laissées en titres ici :

• Livrables / templates : comment Claude doit rendre un code à copier, sans mockup ASCII inutile, avec un résumé de 3 à 5 lignes.
• Gestion des tâches : les cinq étapes, de la planification à l'apprentissage après correction.
• Mémoire et clôture : le rôle précis des quatre fichiers tasks/, la règle qui évite de recharger tout l'historique, et la clôture de session.

Le fichier complet, propre et prêt à copier, t'attend juste en dessous.