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

[GN⁺]

Avis Hacker News

• Claude a parfois tendance à ignorer les instructions de CLAUDE.md
  Plus le fichier contient d’informations sans rapport avec la tâche en cours, moins Claude suit ces consignes
  Un ami avait demandé à Claude de l’appeler « Mr Tinkleberry », et quand Claude l’oubliait, c’était un bon indicateur qu’il ignorait le fichier

• J’utilise depuis longtemps l’approche table des matières
  Je sépare les consignes par tâche dans des fichiers markdown distincts, et je ne mets dans CLAUDE.md que leur liste avec une brève description
  Cela permet de garder la fenêtre de contexte propre
  On peut voir mon exemple de fichier ici

  • J’ai essayé la même méthode, mais les résultats étaient irréguliers
    Claude lisait très rarement les autres fichiers de documentation

• J’ai l’impression que donner trop de contexte à Claude finit par dégrader la qualité
  Du coup, je maintiens toujours deux versions du code

  1. le code source brut, sans commentaires ni espaces superflus
  2. le code avec commentaires
     Je ne donne au LLM que la première version
     Je pense que le point clé, c’est le ratio calcul / information. La capacité de calcul est limitée
  • J’ai eu une expérience similaire, mais mettre les éléments répétitifs dans un fichier de notes Claude a amélioré l’efficacité
    Il n’est pas nécessaire d’y mettre absolument tout, mais y mettre les informations essentielles avait un ROI élevé
    Claude fonctionne bien sur des projets classiques, mais il se perd souvent avec de nouveaux frameworks ou outils
  • Tu dis que tu maintiens deux versions du code, et je me demande comment tu gères leur cohérence
    J’aimerais savoir si tu utilises un script qui enlève les commentaires et les espaces après les modifications
  • Je pense qu’il faut maintenir une forte densité d’information dans les fichiers de documentation
  • Tu dis que tu ne donnes pas au LLM la version avec commentaires, mais je me demande comment tu fais ça en pratique
  • Au final, l’attention est finie. Si on surcharge le contexte, la concentration se disperse

• En réalité, il existe une solution même sans toute cette configuration complexe
  C’est tout simplement de documenter clairement le code
  Si chaque fichier explique brièvement ce qu’il fait, cela sert déjà de prompt
  Il suffit d’utiliser README.md de manière active
  Les LLM ont déjà été entraînés sur des informations publiques, donc il n’y a pas besoin d’inventer quelque chose de nouveau

  • Mais quand on écrit de la documentation pour une IA, il faut une approche différente de celle utilisée pour des lecteurs humains
    Le simple conseil « documentez bien votre code » n’est pas adapté à ce contexte
  • Moi aussi, je pense que la communauté IA a parfois tendance à réinventer inutilement la roue
    README est utile, mais CLAUDE.md a un autre objectif
    Par exemple, Claude/agents.md peut être automatiquement injecté dans le contexte lors de l’accès à un répertoire donné
    Dans des bases de code complexes, la gestion du contexte devient bien plus importante
  • CLAUDE.md n’est pas un simple document ; il sert à personnaliser le prompt initial du modèle
    Donc le conseil « il suffit d’écrire un bon prompt » passe à côté de l’essentiel
  • Par exemple, où faut-il écrire une règle comme « les requêtes de base de données doivent toujours utiliser un index » ?
    Si on la met dans le README, cela finit par jouer le même rôle que CLAUDE.md
    Le but de CLAUDE.md est de fournir à l’avance les informations clés pour que Claude n’ait pas à relire toute la documentation à chaque fois
    Les humains se souviennent, mais Claude oublie à chaque tâche, donc il faut une structure qui réduise le ré-onboarding

• Franchement, s’il faut aller jusqu’à mettre en place une infrastructure IA de ce niveau, j’ai l’impression qu’il vaut mieux coder moi-même

  • Mais les réglages liés au style ne se font qu’une seule fois, puis peuvent être réutilisés
    Je gère séparément les règles communes et les règles spécifiques à chaque projet
  • La configuration évoquée dans l’article peut être faite en quelques heures
    Ne pas utiliser l’IA, c’est simplement une perte de productivité
  • On peut aussi confier l’essentiel de la configuration initiale au LLM
  • En réalité, cela ne demande pas tant d’efforts. Le problème, c’est surtout la tendance à sur-optimiser les outils
  • L’important, c’est de savoir si le coût est récurrent ou ponctuel
    Si la configuration n’est nécessaire qu’une seule fois, l’investissement vaut largement le coup
    Dire que « la configuration est pénible », c’est un peu comme les excuses de ceux qui évitent de configurer leur débogueur

• Moi, je copie-colle simplement le code nécessaire dans la fenêtre de discussion et je m’en sers comme dans une conversation
  Les modèles se sont tellement améliorés ces derniers temps qu’on obtient déjà des résultats tout à fait corrects sans fichier .md
  Ces fichiers apportent peut-être une légère amélioration, mais je ne pense pas que ce soit une magie de productivité x100

  • Mais c’est un autre cas d’usage
    Ici, on parle de situations où Claude réalise lui-même une implémentation complète ou corrige un bug
  • J’ai eu une expérience similaire. J’ai créé un CLAUDE.md une fois, mais je ne l’utilise plus maintenant
    Il suffit de donner le contexte nécessaire pour que ça marche très bien. Ça ressemble un peu à du bikeshedding
  • Malgré tout, préparer à l’avance la liste des tables ou des colonnes d’une base de données peut réduire les répétitions

• Moi, je demande à Claude de rédiger lui-même CLAUDE.md
  Si on lui dit « README.md est pour les utilisateurs, CLAUDE.md est pour toi »,
  il met aussi automatiquement à jour des consignes comme « vérifie toujours la documentation de l’API »
  Pas besoin de connaître un prompt magique tant que le résultat est bon

  • Mais je me demande s’il existe des preuves que des consignes écrites par l’IA soient meilleures que celles écrites par des humains
    Rien ne dit vraiment qu’une IA sache mieux se prompter elle-même