Rédiger le meilleur CLAUDE.md : guide complet pour Claude Code

L'invite système de Claude Code occupe déjà environ 50 instructions avant même le début de votre session. Des recherches sur les LLM de pointe montrent que le suivi des instructions commence à se dégrader aux alentours de 150 à 200 instructions au total, ce qui vous laisse environ 100 à 150 emplacements pour tout ce que vous souhaitez que Claude sache sur votre projet. 

CLAUDE.md est le fichier qui remplit ces emplacements. C'est un fichier markdown que Claude Code lit au début de chaque session, ce qui lui fournit un contexte persistant sur votre base de code sans que vous ayez à vous répéter. Mais Claude filtre activement le contenu qu'il considère comme non pertinent pour la tâche en cours. Un fichier trop verbeux ne fait pas que gaspiller de la place ; il entre en concurrence avec vos véritables règles.

Ce tutoriel explique comment construire un CLAUDE.md où chaque ligne compte : quoi inclure, quoi écarter, comment l'organiser pour des équipes, et comment le garder utile dans le temps.

Je vous recommande également de consulter nos autres guides récents sur Claude Code :

• Claude Code Plan Mode
• Claude Code dans Docker
• How to Build Claude Code Plugins
• Using Claude Code With Ollama Local Models

Qu'est-ce qu'un fichier CLAUDE.md ?

CLAUDE.md est un fichier markdown que Claude Code charge automatiquement au début de chaque conversation. Il se trouve à la racine de votre projet et fournit à Claude des consignes permanentes sur toutes sortes d'éléments pertinents : 

• La stack technique que vous utilisez
• Comment vous exécutez les tests
• Les conventions qui comptent
• Ce qu'il ne faut pas modifier

Sans lui, chaque session repart de zéro. Vous réexpliquez le même contexte, corrigez les mêmes suppositions, et voyez Claude refaire les mêmes erreurs qu'hier. CLAUDE.md corrige cela en encodant une bonne fois pour toutes la connaissance de votre projet.

C'est l'un des plusieurs systèmes de contexte utilisés par Claude Code, chacun ayant un rôle différent :

L'exécution de /init génère un CLAUDE.md de départ en analysant votre base de code, en détectant les systèmes de build, frameworks de test et motifs de code. Si un fichier existe déjà, il propose des améliorations au lieu d'écraser le contenu. C'est un point de départ correct, mais le fichier est trop important pour être laissé en pilote automatique.

Point important : le contenu de CLAUDE.md survit aussi à /compact. Lorsque le contexte est compressé en cours de session, Claude relit le fichier sur le disque et le réinjecte tel quel.

Emplacements et priorité des fichiers

Les fichiers CLAUDE.md peuvent vivre à quatre endroits, du plus large au plus spécifique :

• Politique gérée (à l'échelle de l'organisation) : /Library/Application Support/ClaudeCode/CLAUDE.md sur macOS. S'applique à tous les utilisateurs de la machine et ne peut être exclu par aucun réglage. Sous Linux/WSL, il se trouve à /etc/claude-code/CLAUDE.md, et sous Windows à C:\Program Files\ClaudeCode\CLAUDE.md.

• Niveau utilisateur : ~/.claude/CLAUDE.md. Consignes personnelles s'appliquant à tous les projets sur votre machine.

• Niveau projet : ./CLAUDE.md ou ./.claude/CLAUDE.md à la racine du dépôt. C'est celui que vous validez dans git et partagez avec votre équipe.

• Sous-répertoire : ./subdir/CLAUDE.md. Limité à ce répertoire et chargé à la demande lorsque Claude lit des fichiers à cet endroit, pas au démarrage de la session.

Les fichiers plus spécifiques ont priorité sur les plus généraux. Si votre CLAUDE.md de projet indique « utiliser des tabulations » et que votre fichier au niveau utilisateur indique « utiliser des espaces », c'est le fichier projet qui l'emporte.

Pour des préférences personnelles qui ne doivent pas finir dans le contrôle de version, créez un CLAUDE.local.md et ajoutez-le à .gitignore. Mettez ici les spécificités d'éditeur, styles de commit préférés ou dérogations temporaires, plutôt que de polluer le fichier partagé.

Une fois l'emplacement et les interactions clarifiés, reste à décider ce qui doit réellement figurer dedans.

Que mettre dans votre CLAUDE.md

Un CLAUDE.md s'articule en trois couches : 

1. Ce qu'est le projet
2. Pourquoi il fonctionne de cette manière
3. Comment Claude doit agir dans ce cadre

Si vous avez lu Claude Code Best Practices, vous reconnaîtrez le même principe appliqué à une surface plus étroite. (Si ce n'est pas le cas, nous vous conseillons vivement de le lire après cet article.)

Aperçu de projet à fort signal

Commencez par une description du projet en une ou deux phrases et votre stack technique avec les versions. Claude peut déduire beaucoup en lisant votre code, mais il ne devinera pas que vous êtes sur Next.js 15 plutôt que 14, ou que vous avez choisi Drizzle plutôt que Prisma.

Ajoutez une carte de la structure des répertoires. Pas chaque fichier, seulement l'organisation de haut niveau avec de brèves descriptions :

src/
  data/        # Data loading and preprocessing pipelines
  models/      # Model definitions and training loops
  evaluation/  # Metrics, validation, experiment tracking
  api/         # FastAPI endpoints for model serving
  tests/       # Co-located with source, test_*.pyPropulsé par

Placez les commandes courantes dans des blocs de code. Build, test, lint et démarrage du serveur de dev. Une commande dans une clôture de code est quelque chose que Claude exécutera tel quel. Une commande rédigée dans une phrase est une suggestion sur laquelle il peut improviser.

Finalité et contraintes

Vos choix d'architecture doivent figurer dans le fichier, sinon Claude prendra les siens. Si vous avez choisi SQLite plutôt que Postgres pour une raison, dites-le. Si votre couche API suit un motif précis, expliquez le raisonnement.

La justification a ici une vraie valeur. « Ne forcez jamais un push » est une consigne plate que Claude peut ignorer sous pression. « Ne forcez jamais un push. Cela réécrit l'historique partagé et est irrécupérable pour les collaborateurs » donne à Claude assez de contexte pour généraliser. Il n'évitera pas seulement git push --force. Il hésitera aussi avant un git reset --hard sur une branche partagée.

Consignes opérationnelles pour Claude

Cela couvre les conventions que Claude ne peut pas déduire en lisant votre code. Si vous utilisez Conventional Commits (feat:, fix:, docs:), mentionnez-le. Si vos branches suivent un schéma de nommage comme initials/description, écrivez-le.

Les spécificités et pièges doivent aussi figurer ici. Chaque base de code en a : le script de migration à exécuter avant les builds, la variable d'environnement à une valeur précise pour que les tests passent, le module qui casse s'il est importé dans le mauvais ordre. Claude est un nouveau membre d'équipe à chaque session, et ce sont les éléments sur lesquels une nouvelle recrue trébuche le premier jour.

Ce que vous pouvez omettre : tout ce que Claude sait déjà grâce au langage lui-même. Inutile de lui dire d'utiliser async/await en JavaScript moderne ou de préférer pathlib en Python 3. Si une convention est le comportement par défaut du langage, l'écrire ajoute du bruit qui masque les consignes vraiment importantes.

Comment rédiger un fichier CLAUDE.md

Définir le contenu juste est la partie facile. Le plus difficile, c'est d'écrire des consignes que Claude suivra réellement, et de savoir quoi retirer.

Rédiger des consignes efficaces

La précision l'emporte toujours sur l'intention. « Formatez correctement le code » ne dit rien à Claude. « Indentation de 2 espaces, pas de point-virgule, guillemets simples » lui dit exactement quoi faire et lui donne un critère vérifiable.

Appliquez ce test à chaque ligne : « Supprimer cette ligne ferait-il commettre des erreurs à Claude ? » Si la réponse est non, la ligne s'en va. La recommandation officielle est de rester sous 200 lignes par fichier, et certaines équipes expérimentées tournent avec moins de 60. Ce n'est pas du minimalisme pour le principe : un fichier plus court augmente la probabilité d'être lu en entier.

Limitez les niveaux de titres à trois au maximum. Utilisez des noms de sections que les agents reconnaissent par analogie avec les READMEs : Commands, Structure, Conventions, Testing. Se montrer créatif avec les intitulés ajoute de la friction, car Claude a vu des millions de READMEs et a des attentes fortes sur ce qui se trouve où.

Si une règle est ignorée malgré sa présence dans le fichier, n'ajoutez pas plus de mots autour. Préfixez-la par IMPORTANT : ou VOUS DEVEZ. Mais utilisez cela avec parcimonie, car l'emphase s'émousse. Si tout est marqué important, plus rien ne l'est.

Ce qu'il faut laisser de côté

L'application du style de code est le piège numéro un. Formatage, indentation, ordre des imports : ce sont des problèmes déterministes avec des solutions déterministes. Des linters et formatteurs comme Biome, ESLint ou Ruff les gèrent plus vite, à moindre coût et avec une constance de 100 %. Dépenser du budget d'instructions pour des règles de style est du poids mort : le même travail qu'un hook pre-commit fait gratuitement.

Les conventions standard du langage sont aussi à exclure, puisque Claude connaît déjà les schémas TypeScript et les idiomes Python. La documentation d'API complète doit être liée plutôt que collée. Les consignes spécifiques à des tâches particulières qui ne s'appliquent qu'à certains workflows vont dans les skills, où elles se chargent à la demande au lieu de prendre de la place à chaque session.

Un schéma à signaler : les contraintes uniquement négatives. « N'utilisez jamais --legacy-peer-deps » laisse Claude sans solution lorsqu'il rencontre un conflit de dépendances. Associez chaque interdiction à une directive : « N'utilisez jamais --legacy-peer-deps ; résolvez les conflits en mettant à jour le package vers une version compatible. » Si vous avez travaillé avec les Cursor Rules ou d'autres fichiers de configuration IA similaires, vous retrouverez ce principe partout.

Avant / après : un exemple minimaliste réel

Voici la différence en pratique. À gauche, une section CLAUDE.md auto-générée typique, pleine de conseils génériques que Claude connaît déjà. À droite, la même section après application du test de spécificité : seules les informations propres au projet subsistent.

La seconde version est plus courte et indique à Claude des éléments qu'il ne peut pas inférer à partir de la base de code.

Construire le fichier à partir de zéro

Exécutez /init à la racine de votre projet pour obtenir un point de départ généré. Relisez chaque ligne, supprimez l'évidence, et ajoutez ce qui manque par rapport à la manière dont votre équipe travaille réellement. Partir de la sortie /init est plus rapide que partir d'une page blanche, mais le contenu auto-généré ne doit jamais être livré sans relecture.

Si vous préférez écrire de zéro, commencez par cinq sections : 

1. Vue d'ensemble du projet
2. Carte des répertoires
3. Commandes
4. Conventions
5. Spécificités

Vous pourrez toujours étoffer le fichier plus tard, et partir minimal vous garantit que chaque ligne ajoutée vient d'une erreur réelle plutôt que d'une hypothèse.

Deux signaux indiquent qu'il faut faire de la maintenance : 

• Claude s'excuse d'avoir manqué une consigne déjà présente : la formulation est ambiguë, réécrivez-la.
• La même règle est violée sur plusieurs sessions : le fichier est trop long et Claude le filtre, raccourcissez-le.

Dans les deux cas, le remède est le même : moins de mots, une structure plus claire.

Faire évoluer les fichiers CLAUDE.md pour les équipes

Pour un seul développeur, le fichier peut rester maigre indéfiniment. Dès qu'une équipe s'en mêle, il faut une structure différente.

Contrôle de version et propriété partagée

Votre CLAUDE.md au niveau projet a sa place dans git. C'est une documentation partagée qui s'améliore à mesure que les coéquipiers y ajoutent des règles issues de leurs propres erreurs. Traitez les modifications comme des PRs de code : relisez-les, et demandez-vous si chaque nouvelle ligne mérite sa place.

Quand les conventions s'empilent au-delà de ce qu'un seul fichier peut contenir, déplacez-les dans .claude/rules/. Chaque fichier Markdown couvre un sujet, avec des noms explicites : testing.md, api-design.md, database-migrations.md. Claude découvre ces fichiers de manière récursive et les charge avec la même priorité que le CLAUDE.md principal.

Des règles limitées par chemin rendent le tout plus ciblé. Ajoutez un front matter YAML et la règle ne se chargera que lorsque Claude travaille sur des fichiers correspondants :

---
paths:
  - "src/api/**/*.ts"
---
# API conventions go herePropulsé par

Vos conventions front-end ne consommeront pas le budget d'instructions lors du travail back-end, et inversement.

Dans les monorepos où des équipes ont des conventions conflictuelles, claudeMdExcludes empêche le chargement de certains fichiers :

{
  "claudeMdExcludes": [
    "**/other-team/.claude/rules/**"
  ]
}Propulsé par

Placez ceci dans .claude/settings.local.json pour le garder hors du contrôle de version.

Divulgation progressive et modularisation

Faire grossir un CLAUDE.md donne souvent envie de centraliser : un gros fichier qui contient tout. C'est l'inverse qu'il faut faire. Scinder le CLAUDE.md d'un monorepo en fichiers au niveau des services peut réduire le nombre total de mots de 80 % tout en améliorant le respect des règles par Claude : moins à lire par session signifie moins à filtrer.

Le principe : pointer, ne pas embarquer. Au lieu de @path/to/big-doc.md (qui charge tout le fichier dans chaque session), écrivez « Pour les procédures de migration, voir docs/migrations.md. » Claude le lira quand il aura besoin de l'information. La syntaxe d'import @ convient pour de petits fichiers, mais tout ce qui est substantiel est mieux cité que intégré.

Les fichiers CLAUDE.md de sous-répertoires complètent ce schéma. Un frontend/CLAUDE.md avec des conventions React ne se charge que lorsque Claude touche des fichiers dans ce répertoire. Les règles back-end restent à l'écart pendant le travail front-end.

Entretenir votre fichier CLAUDE.md

La structure à l'échelle est en grande partie un problème résolu une fois les briques de base acquises. Mais les projets évoluent, et les conventions aussi. Des règles pertinentes il y a six mois deviennent du bruit qui masque celles qui comptent aujourd'hui. L'enjeu constant est de garder le fichier honnête dans le temps.

Garder le fichier à jour

Ajoutez des règles plus lentement que vous ne le pensez. Une nouvelle ligne mérite d'entrer dans le fichier uniquement lorsque Claude a commis une erreur réelle qu'elle aurait empêchée. Chaque règle doit remonter à un incident réel, pas à une hypothèse.

Le mouvement inverse compte tout autant : si Claude suit déjà une convention sans qu'on le lui dise, cette règle est du poids mort. Supprimez-la et libérez du budget d'instructions pour des règles qui changent le comportement.

Une habitude de maintenance peu coûteuse consiste à demander à Claude, « Passe en revue ce CLAUDE.md et propose des améliorations » toutes les quelques semaines. Il repère les contradictions entre règles, signale les recouvrements et identifie les formulations à resserrer. 

Vous pouvez aussi ajouter une consigne permanente dans le fichier lui-même : « Lorsque vous rencontrez une mauvaise supposition pendant une session, proposez une correction du CLAUDE.md. » Cela crée une boucle de feedback où le fichier s'améliore au fil de l'usage.

Anti-patterns à éviter

Le piège le plus courant est l'accumulation. Des règles s'ajoutent après chaque session frustrante, personne ne retire celles qui ne servent plus, et au final, le fichier est si long que Claude en filtre la moitié. Quand Claude ignore une règle, ajouter de l'emphase par-dessus un fichier obèse ne réglera rien. Il faut élaguer.

Si vous utilisez des imports @ pour de gros fichiers, c'est le deuxième point à vérifier. Un document d'architecture de 500 lignes importé avec @ embarque l'intégralité du texte dans chaque session, et consume votre budget d'instructions avant même que Claude n'intègre vos premières vraies règles. Référencez-le plutôt.

Générer avec /init et ne jamais éditer la sortie est une recette pour des comportements dégradés partout. Une mauvaise consigne dans CLAUDE.md n'affecte pas qu'une seule réponse. Elle façonne la recherche, la planification et l'implémentation de Claude à chaque session jusqu'à ce que quelqu'un la corrige.

Des règles contradictoires à travers plusieurs fichiers entraînent un comportement imprévisible. Quand deux règles s'opposent, Claude en choisit une sans vous dire laquelle. C'est encore pire dans les projets combinant un CLAUDE.md racine avec plusieurs fichiers .claude/rules/. Une revue périodique de tous les fichiers de consignes est la seule prévention.

Toutes les erreurs ne méritent pas une nouvelle règle. Certaines sont des cas isolés. Ajouter une règle pour chaque cas limite crée un fichier plein de conditions utiles dans des situations rares et nuisibles dans la majorité des sessions. L'objectif reste inchangé : un fichier court où chaque ligne influe sur le comportement.

Conclusion

CLAUDE.md est probablement le fichier le plus structurant d'un projet Claude Code. Il façonne chaque session avant même qu'un prompt ne soit saisi, et un fichier bien entretenu produit des effets cumulatifs semaine après semaine.

Si vous n'en avez pas encore, exécutez /init, lisez la sortie, et supprimez chaque ligne qui n'éviterait pas une erreur réelle. Si vous en avez un, ouvrez-le maintenant et appliquez le même test. Si votre CLAUDE.md doit être énorme pour expliquer votre projet, c'est le signe que l'outillage du projet est trop complexe, pas que vous avez besoin d'un fichier plus gros.

La bonne prochaine étape : auditez votre dépôt et rédigez une base aujourd'hui. Commencez par cinq sections, restez sous les 60 lignes, et laissez les erreurs réelles guider chaque ajout.

Si vous souhaitez créer des outils avec l'API Anthropic, notre cours Introduction to Claude Models couvre l'ensemble de la gamme et vous apprend à les utiliser efficacement.