Comment bien rédiger un bon `CLAUDE.md`

• Comme un LLM est une fonction sans état, CLAUDE.md sert de document clé pour présenter la base de code à Claude à chaque session
• Le fichier doit contenir de façon concise le WHAT (structure), le WHY (objectif) et le HOW (mode de fonctionnement) du projet, et un excès de commandes inutiles peut dégrader les performances
• Claude peut ignorer le contenu de CLAUDE.md s’il estime, selon les consignes du message système, qu’il n’est pas pertinent
• Un fichier efficace ne contient que des informations courtes et applicables de manière générale, tandis que les consignes détaillées doivent être séparées dans d’autres documents selon une approche de Progressive Disclosure
• CLAUDE.md étant le point d’impact le plus élevé du harnais d’agent, il faut l’écrire soigneusement à la main plutôt que de le générer automatiquement

---

Le caractère sans état des LLM et le rôle de CLAUDE.md

• Les LLM utilisent des poids figés au moment de l’inférence et ne conservent ni apprentissage ni mémoire entre les sessions
  • Le modèle doit donc recevoir sous forme de tokens d’entrée toutes les informations nécessaires pour comprendre la base de code
• Les agents de code comme Claude Code doivent gérer explicitement la mémoire, et CLAUDE.md est le seul fichier automatiquement inclus dans toutes les conversations
• Cela rend les trois points suivants indispensables
  1. Au début d’une session, Claude ne sait rien de la base de code
  2. Il faut lui redonner les informations nécessaires à chaque session
  3. Le moyen standard pour cela est CLAUDE.md

Onboarding de la base de code : WHAT, WHY, HOW

• CLAUDE.md joue le rôle de document d’onboarding pour aider Claude à comprendre le projet
  • WHAT : fournit une carte du code, comme la stack technique, la structure du projet ou l’organisation du monorepo
  • WHY : explique l’objectif et la fonction de chaque composant
  • HOW : précise comment exécuter les tâches concrètes comme le build, les tests ou le typecheck
• En revanche, lister toutes les commandes est inefficace ; il faut n’inclure que le strict minimum d’informations nécessaires

Pourquoi Claude ignore parfois CLAUDE.md

• Claude Code insère dans le message utilisateur un rappel système du type suivant

  IMPORTANT: this context may or may not be relevant...
  

  • À cause de cela, Claude ignore ce contexte s’il juge qu’il n’est pas lié à la tâche en cours
• Plus le fichier contient de consignes peu universelles, plus il risque d’être ignoré
• On suppose qu’Anthropic a ajouté ce mécanisme parce qu’ignorer les consignes inutiles améliorait la qualité des résultats

Principes pour rédiger un bon CLAUDE.md

Less (instructions) is more

• Un LLM peut suivre de manière stable environ 150 à 200 consignes
  • Plus le modèle est petit, plus la dégradation est brutale, et les tâches à plusieurs étapes lui conviennent moins
• Le prompt système de Claude Code contient déjà environ 50 consignes
  • CLAUDE.md ne doit donc contenir qu’un minimum de consignes universelles et indispensables
• Plus le nombre de consignes augmente, plus la qualité d’exécution de l’ensemble des consignes diminue de façon uniforme

Longueur du fichier et périmètre d’application

• Les LLM fonctionnent mieux avec un contexte concentré et fortement pertinent
• Comme CLAUDE.md est inclus dans toutes les sessions, il faut n’y conserver que des informations applicables de manière générale
• En règle générale, il est recommandé de rester sous les 300 lignes, et si possible encore moins
  • Le fichier d’exemple de HumanLayer fait moins de 60 lignes

Progressive Disclosure

• Dans les grands projets, il est difficile de tout mettre dans un seul fichier, d’où la recommandation d’une approche de Progressive Disclosure
  • Les consignes détaillées sont séparées dans des fichiers Markdown distincts du dossier agent_docs/
  • Exemples : building_the_project.md, running_tests.md, code_conventions.md, etc.
• CLAUDE.md ne doit contenir que la liste de ces fichiers et une brève description, ainsi qu’une instruction indiquant à Claude de les lire si nécessaire
• Il vaut mieux utiliser des références file:line plutôt que des extraits de code afin de garder les informations à jour
• Cette approche ressemble au concept de Claude Skills, mais elle met l’accent sur la gestion des consignes plutôt que sur l’usage des outils

Claude n’est pas un linter

• Inclure des règles de style de code dans CLAUDE.md est inefficace
  • Les LLM sont coûteux, lents et moins déterministes qu’un linter
• Les règles de style sont apprises naturellement à partir des motifs du code existant, sans qu’il soit nécessaire d’ajouter des consignes spécifiques
• Pour le formatage, mieux vaut utiliser des linters auto-correctifs (comme Biome) et ne transmettre à Claude que le résultat des corrections
• Si nécessaire, on peut automatiser le formatage et la validation avec un Stop Hook ou une Slash Command

Pas de génération automatique

• Un CLAUDE.md créé avec la commande /init ou une fonctionnalité de génération automatique est déconseillé
  • Ce fichier est en effet un point à fort levier qui influence toutes les sessions et tous les livrables
• Une seule ligne de consigne erronée peut avoir un effet en chaîne négatif sur la qualité globale du code
• Il faut donc relire soigneusement chaque phrase et rédiger le document à la main

Conclusion

• CLAUDE.md est un document destiné à onboarder Claude sur la base de code, et il doit définir clairement les WHY, WHAT et HOW
• Il faut réduire au minimum les consignes et ne conserver que des contenus universels et concis
• L’approche Progressive Disclosure permet de fournir les informations nécessaires par étapes
• Il ne faut pas utiliser Claude comme linter, mais l’associer à des outils dédiés ainsi qu’à des hooks et commandes
• Plutôt que la génération automatique, il faut privilégier une rédaction manuelle soigneuse afin de maximiser la qualité globale du harnais