Skip to Content
Claude CodePartie 3 — CLAUDE.md, mémoire & conventions3.2 — Écrire un bon CLAUDE.md

Chapitre 3.2 — Écrire un bon CLAUDE.md

⏱️ TL;DR — Un bon CLAUDE.md est court, priorisé, prescriptif et tranchable. Il liste ce que l’agent doit savoir en permanence, règles vitales en haut, et rien de superflu — parce que chaque ligne est payée à chaque tâche. Démarre avec /init pour une base, puis taille : supprime tout ce que l’agent fait déjà bien sans qu’on le lui dise, et déplace vers un hook tout ce qui est mécanique. Un CLAUDE.md se jardine, il ne se remplit pas.

🎯 Objectifs

  • Appliquer les quatre qualités d’un bon CLAUDE.md : court, priorisé, prescriptif, tranchable.
  • Utiliser /init comme point de départ, puis élaguer.
  • Reconnaître et corriger le CLAUDE.md obèse.
  • Savoir ce qui ne doit pas y figurer.

Les quatre qualités

Court

Le réflexe contre-intuitif : moins tu en mets, plus il est suivi. Un fichier de 40 lignes ciblées bat un fichier de 400 lignes fourre-tout, parce que l’agent (comme un humain) dilue son attention sur un mur de texte. Vise l’essentiel : la stack, 6-10 conventions structurantes, les invariants, la façon de vérifier. Si tu hésites à couper une ligne, c’est probablement qu’elle doit partir.

Priorisé

Le haut du fichier pèse plus lourd. Ordonne du non négociable au secondaire :

# Projet X — Guide agent
## Non négociable
- ...   ← les règles qui, violées, cassent tout
## Conventions
- ...   ← le quotidien
## Bon à savoir
- ...   ← contexte utile, moins critique

Prescriptif

Dis quoi faire (ou ne pas faire), à l’impératif, pas des généralités. « Utilise des server actions pour les mutations » guide ; « privilégier de bonnes pratiques de data-fetching » ne guide rien.

Tranchable

Chaque règle doit permettre de dire, sur un bout de code, « respectée » ou « violée ». no-any, alias @/, « pas de fetch dans les composants serveur » : tranchables. « Écris du beau code » : intranchable → poubelle. (Rappel de 2.4 : une règle intranchable est un vœu.)

💡 Réflexe d’architecte — Passe chaque ligne au test : « Puis-je écrire un exemple qui la respecte ET un qui la viole ? » Si non, reformule ou supprime. Un CLAUDE.md 100 % tranchable est aussi un CLAUDE.md dont tu peux déléguer l’application à des hooks/lint (Partie 7).

/init puis tailler

/init génère un premier CLAUDE.md en analysant ton repo (stack détectée, scripts, structure). C’est un point de départ, pas un livrable :

/init

Ce qu’il produit est souvent trop verbeux et descriptif (« ce projet utilise React… »). Ton travail ensuite : tailler.

  • Supprime le descriptif que l’agent déduit tout seul (il voit que c’est du React).
  • Garde/ajoute le prescriptif qu’il ne peut pas deviner (tes choix, tes interdits).
  • Réordonne : vital en haut.

⚠️ Piège — Prendre la sortie de /init telle quelle et ne jamais y retoucher. C’est le chemin le plus court vers le CLAUDE.md obèse : plein de descriptions inutiles, tes vraies règles noyées au milieu. /init amorce, tu affines.

Le principe d’élagage permanent

Règle d’or de la communauté : si l’agent fait déjà une chose correctement sans que tu la lui dises, retire-la du CLAUDE.md. Elle ne fait qu’occuper de la place. Et si une règle est mécaniquement vérifiable, déplace-la vers un hook (le harness la garantit, sans coût de contexte).

Un CLAUDE.md sain rétrécit avec le temps : à mesure que tu automatises (hooks) et que tu constates ce que l’agent gère nativement, tu enlèves. C’est un jardin, pas un grenier.

Bon vs mauvais : côte à côte

❌ Obèse et vague

# Mon projet
Ce projet est une application web moderne construite avec Next.js et React.
Nous utilisons TypeScript pour la sécurité des types. Il est important d'écrire
du code propre, lisible et maintenable. Merci de suivre les bonnes pratiques de
l'industrie et de bien tester. Nous aimons le code performant. Utilise des noms
de variables clairs. Le dossier src contient le code source. Les composants sont
dans components. (… 300 lignes de ce genre …)

✅ Court, prescriptif, tranchable

# TaskFlow — Guide agent
## Non négociable
- TypeScript strict. `any` interdit (utilise `unknown` + narrowing).
- Mutations : server actions dans `actions.ts`. Jamais de mutation dans un composant.
- UI réutilisable : uniquement `src/components/ui/`, style calqué sur `button.tsx`.
## Conventions
- Dossiers : `src/features/<feature>/` (queries.ts, actions.ts, schema.ts, components/).
- Imports : alias `@/`. Interdit : `../../..`.
- Couleurs : tokens sémantiques CSS, jamais de hex en dur.
## Vérifier avant de conclure
- `npm run lint && npm test && npm run build` doivent passer.

Le second tient en 15 lignes, ne décrit rien que l’agent voit déjà, et chaque ligne est vérifiable.

Ce qui NE va PAS dans le CLAUDE.md

  • Du descriptif déductible (« c’est du React »).
  • Des automatismes (« formate après édition ») → hook.
  • Des specs / du backlog / un journal → issues, docs, ADR.
  • Des secrets / chemins de ta machine → CLAUDE.local.md ou variables d’env.
  • Une capacité complexe et ponctuelle (« sais générer un rapport de perf ») → skill.

🧭 Sur TaskFlow — En 3.5, on partira de la graine et on résistera à la tentation de tout y mettre. Chaque ajout devra passer les quatre tests (court/priorisé/prescriptif/tranchable) et le filtre d’élagage. Objectif : un fichier que l’agent suit réellement, pas un fichier qui a l’air complet.

✏️ Exercices

Exercice 1 — Cure d’amaigrissement. Prends un CLAUDE.md existant (ou lance /init sur un repo). Coupe-le de moitié en appliquant l’arbre d’élagage. Que reste-t-il ?

✅ Solution

Il reste en général : la stack (les choix non déductibles), 6-10 conventions prescriptives, les invariants, et la façon de vérifier. Disparaissent : les descriptions (« ce projet utilise… »), les vœux (« code propre »), les automatismes (à passer en hook). Un fichier deux fois plus court est souvent deux fois mieux suivi.

Exercice 2 — Test de tranchabilité. Pour chaque ligne de ton CLAUDE.md, écris un exemple conforme et un exemple fautif. Barre toute ligne pour laquelle tu n’y arrives pas.

✅ Solution

Les lignes qui survivent sont opérationnelles (on peut les vérifier). Celles qu’on barre étaient des vœux. Bonus : les lignes tranchables et mécaniques sont exactement celles que tu automatiseras en hooks — tu prépares déjà la Partie 7.

🧠 Quiz de révision

1. Pourquoi « plus court » = « mieux suivi » ?

Parce que l’agent dilue son attention sur un mur de texte, comme un humain. Un fichier court et ciblé met en avant les vraies règles ; un fichier obèse les noie. Et chaque ligne coûte du contexte à chaque tâche.

2. Que faire de la sortie de /init ?

L’utiliser comme point de départ, puis tailler : supprimer le descriptif déductible, garder/ajouter le prescriptif non devinable, réordonner (vital en haut). Jamais la laisser telle quelle.

3. Règle d’élagage : que faire d’une ligne que l’agent respecte déjà sans elle ?

La supprimer : elle n’apporte rien et occupe du contexte. Le CLAUDE.md doit rétrécir avec le temps, pas grossir.

4. Une règle mécanique et vérifiable : CLAUDE.md ou hook ?

Hook : le harness la garantit, sans coût de contexte ni dépendance à l’attention du modèle. Le CLAUDE.md garde le guidage non automatisable.

5. Cite deux choses à NE PAS mettre dans le CLAUDE.md.

Par exemple : du descriptif déductible (« c’est du React ») et des automatismes (« formate après édition », → hook). Aussi : specs/backlog/journal, secrets/chemins machine, capacités complexes ponctuelles (→ skill).

Chapitre suivant : Des conventions qui tiennent — au-delà du fichier, comment faire pour qu’une convention soit vraiment respectée.

3.1 — Anatomie du CLAUDE.md3.3 — Des conventions qui tiennent