Écrire un CLAUDE.md qui tient la route : le guide complet

Si tu utilises Claude Code, l’assistant d’Anthropic qui travaille directement dans ton terminal ou ton éditeur, tu as déjà remarqué une chose : à chaque nouvelle session, il repart de zéro. Il ne se souvient ni de tes conventions, ni de tes commandes, ni de la remarque que tu lui as faite hier. Sa seule mémoire permanente écrite par toi tient dans un fichier : le CLAUDE.md, qu’il lit au démarrage de chaque conversation.

Ce fichier est donc l’endroit le plus rentable de tout ton projet où investir du temps d’écriture. Et pourtant, la plupart des CLAUDE.md en circulation ne changent rien au comportement de l’assistant. Anthropic le dit sans détour dans sa documentation officielle : un fichier gonflé pousse Claude à ignorer les instructions qu’il contient, y compris les bonnes.

La différence entre un fichier décoratif et un fichier qui pilote vraiment tient à quelques principes précis : prescrire au lieu de décrire, formuler des contraintes vérifiables, poser des garde-fous de processus, et rester court. Ce guide les passe tous en revue, chemins de fichiers et commandes à l’appui, puis les montre à l’œuvre sur un cas d’étude que je connais bien : le CLAUDE.md et le prompt qui pilotent la rédaction de ce blog, article que tu es en train de lire compris.

Ce qu’il te faut

• Claude Code installé, en CLI, dans VS Code ou via l’application de bureau
• un projet réel sur lequel travailler, même petit
• 30 minutes pour écrire la première version, puis des retouches au fil de l’usage

Pourquoi la plupart des CLAUDE.md ne sont pas efficaces

Le CLAUDE.md typique ressemble à un README bis. Il présente le projet, liste les technologies, décrit l’arborescence dossier par dossier, parfois recopie des morceaux de documentation d’API. Tout cela part d’une bonne intention : donner du contexte. Le problème, c’est que Claude n’a aucun besoin de cette aide-là. Lire du code, explorer une arborescence, reconnaître un projet Next.js à son package.json : il le fait très bien tout seul, en quelques secondes, à chaque session. Ton guide touristique ne l’intéresse pas.

Une chose lui échappe pourtant, quelle que soit sa vitesse de lecture : tes attentes. Que la suite de tests se lance avec une commande maison. Que ton équipe interdit les commits directs sur main. Que le dossier des migrations ne se touche jamais sans validation humaine. Qu’une tâche ne compte comme finie que si le lint passe. Aucune lecture de code ne révèle ces règles, parce qu’elles vivent dans ta tête et dans les habitudes de l’équipe. Le CLAUDE.md existe pour les écrire noir sur blanc : il prescrit un comportement au lieu de décrire un projet.

Cette distinction entre décrire et prescrire se voit immédiatement sur des exemples. Le tableau suivant met côte à côte la ligne qu’on trouve partout et celle qui produit un effet.

La colonne de gauche informe sur des faits que le code montre déjà ; la colonne de droite impose des actes que rien dans le code n’impose. Un fichier composé uniquement de lignes de gauche peut faire trois pages sans jamais modifier une seule décision de l’assistant. Trois pages dans le vide, frérot.

Et la longueur aggrave le mal au lieu de le compenser. Le CLAUDE.md est chargé dans la fenêtre de contexte à chaque session, aux côtés de ta conversation et des fichiers lus. Plus il est long, plus il consomme de place, et surtout plus chaque règle individuelle se dilue dans la masse. La documentation d’Anthropic propose un test de coupe d’une simplicité brutale, à appliquer ligne par ligne : « si je retire cette ligne, Claude fera-t-il une erreur ? ». Si la réponse est non, la ligne saute. Un CLAUDE.md de 3 000 lignes échoue à ce test sur 2 900 lignes, et les 100 qui comptent se retrouvent noyées. Taille dans le gras, garde le muscle.

La hiérarchie des fichiers CLAUDE.md : où Claude lit ses instructions

Prescrire plutôt que décrire règle le fond ; reste à poser ces règles au bon endroit, parce que Claude Code ne lit pas un seul fichier mais toute une hiérarchie. Chaque niveau a une portée différente, et une règle placée au mauvais niveau finit soit imposée à des projets qu’elle ne concerne pas, soit invisible pour tes collègues.

La documentation mémoire recense quatre emplacements principaux, du plus large au plus étroit. Le tableau suivant les résume avec leurs chemins exacts.

Tous les niveaux s’additionnent : les fichiers découverts sont concaténés dans le contexte, du plus général au plus proche de ton dossier de travail, sans jamais s’écraser les uns les autres. Le schéma suivant montre l’ordre dans lequel Claude les empile au démarrage d’une session.

L’ordre a une conséquence pratique : les instructions les plus proches de ton dossier de travail sont lues en dernier, et ce choix est voulu, c’est lui qui rend la hiérarchie utilisable dans un monorepo, où un CLAUDE.md à la racine pose les règles communes et chaque sous-projet affine avec le sien. Les fichiers des dossiers parents sont chargés intégralement au lancement ; ceux des sous-dossiers, eux, ne se chargent qu’à la demande, au moment où Claude lit un fichier de ce sous-dossier. Tes règles spécifiques au frontend ne consomment donc aucun contexte tant que la session ne touche pas au frontend.

Deux mécanismes complètent le dispositif. Les imports d’abord : un CLAUDE.md peut inclure d’autres fichiers avec la syntaxe @chemin/vers/fichier, sur une profondeur maximale de quatre niveaux, ce qui permet par exemple de brancher un AGENTS.md existant sans dupliquer son contenu (pour citer un chemin sans déclencher l’import, il suffit de l’entourer de backticks). Les règles ensuite : le dossier .claude/rules/ accueille des fichiers markdown thématiques, et un frontmatter paths avec un motif glob comme src/api/**/*.ts limite leur chargement aux sessions qui touchent réellement ces fichiers.

Pour vérifier ce qui est effectivement chargé, une commande suffit : /context liste les fichiers mémoire pris en compte dans la session courante, et /memory les ouvre pour édition.

Deux informations à lire sur cet écran. La section Memory Files en bas liste les fichiers réellement chargés, ici un CLAUDE.md de projet, celui du dossier parent, et un fichier de mémoire personnelle : c’est la preuve que la hiérarchie décrite plus haut fonctionne. Et la ligne Memory files en haut donne leur coût, environ 1 % de la fenêtre dans cette session. C’est le chiffre à surveiller quand ton fichier grossit.

Si ton fichier n’apparaît pas dans cette liste, inutile d’améliorer sa rédaction : Claude ne le voit pas, et c’est l’emplacement qu’il faut corriger d’abord. Inutile de peaufiner une affiche placardée dans un couloir désert.

Les sections d’un CLAUDE.md qui produisent un effet

Une fois l’emplacement réglé, reste la question du contenu, et la documentation officielle comme la pratique convergent vers cinq familles de sections qui changent réellement le comportement de l’assistant. Les commandes du projet, parce que Claude ne peut pas deviner tes scripts maison ni leurs options. Les conventions qui divergent des défauts, parce qu’il applique spontanément les standards du langage et qu’il faut lui signaler chaque écart voulu. Les zones interdites, parce qu’un assistant zélé « répare » volontiers ce qu’il prend pour un oubli. Le workflow git, parce que les habitudes de branche et de commit varient d’une équipe à l’autre. Et la définition du terminé, parce que sans elle, « ça a l’air de marcher » devient le seul critère d’arrêt.

Ces cinq familles s’assemblent en un squelette qui tient sur une page. Le voici, prêt à copier et à adapter à ton projet.

# Commandes
- npm run dev : serveur local sur le port 3000
- npm test -- --watch=false : la suite complete, obligatoire avant de conclure
- npm run check : typage et lint, zero erreur toleree

# Conventions
- Modules ES (import/export), jamais require
- Indentation 2 espaces, pas de point-virgule
- Messages d'erreur utilisateur en francais, logs techniques en anglais

# Zones interdites
- Ne jamais modifier prisma/migrations/ : ecrire le SQL, le proposer, s'arreter
- Ne jamais toucher aux valeurs de .env, meme pour un exemple
- Aucune dependance ajoutee sans validation explicite

# Workflow git
- Une branche par tache, jamais de commit direct sur main
- Aucun push : je gere la mise en ligne moi-meme

# Definition du termine
- Le build passe, les tests passent, le lint est propre
- Toute tache se conclut par la liste des fichiers modifies et la sortie des tests

Chaque ligne de ce squelette passe le test de coupe : la retirer provoquerait une erreur concrète, une commande devinée de travers, une migration modifiée, un push non désiré. C’est la section « définition du terminé » qui rapporte le plus par rapport à sa taille, parce qu’elle transforme la fin de chaque tâche en engagement chiffré plutôt qu’en impression, un peu comme les serments de la Garde de Nuit dans Game of Thrones, où la parole prononcée engage jusqu’au bout : tant que les tests n’ont pas parlé, le travail n’est pas terminé.

À l’inverse, certaines rubriques classiques échouent systématiquement au test de coupe et méritent d’être exclues d’office : le résumé du projet que le code raconte déjà, la liste des technologies visible dans les manifestes, la documentation d’API qu’un lien remplace, les évidences du type « écrire du code propre », et toute information qui change souvent, condamnée à devenir fausse. Si une de ces rubriques te semble quand même utile, c’est probablement qu’elle cache une règle prescriptive qui n’a pas encore été formulée : extrais la règle, jette la description.

Des contraintes vérifiables plutôt que des intentions

Le squelette fixe les rubriques, mais à l’intérieur de chacune, la formulation décide de tout. Une même intention peut s’écrire de manière vague ou vérifiable, et seule la seconde version est suivie de façon fiable, parce qu’elle ne laisse aucune place à l’interprétation, ni pour l’assistant ni pour toi au moment de contrôler.

Le critère est simple : une contrainte est vérifiable quand un observateur extérieur peut dire, sans discussion possible, si elle a été respectée. « Formate proprement » ne l’est pas ; « indentation 2 espaces » l’est. « Teste tes changements » ne l’est pas ; « lance npm test et colle la sortie » l’est. « Sois prudent avec la base » ne l’est pas ; « aucun DROP, aucun DELETE sans clause WHERE validée par moi » l’est. Chaque fois que tu écris une règle, cherche la reformulation qui la rend contrôlable d’un coup d’œil, et si tu n’en trouves pas, demande-toi si la règle existe vraiment. Une règle invérifiable est un vœu pieux.

Une règle vérifiable gagne encore en précision quand elle montre l’erreur en plus de la consigne : les exemples négatifs multiplient l’effet des règles positives. Interdire « les commentaires inutiles » reste flou ; montrer le commentaire exact qu’on ne veut plus voir, // on incrémente le compteur au-dessus d’un compteur++, supprime toute ambiguïté. Le motif fautif cité tel quel vaut mieux qu’une catégorie abstraite : l’assistant reconnaît un exemple beaucoup plus sûrement qu’il n’interprète une définition. Le mieux, on le verra dans le cas d’étude, c’est de fournir carrément le motif de recherche qui permet de vérifier l’absence du défaut.

Sur les règles critiques, la documentation valide une technique de renforcement assumée : l’emphase. Écrire « IMPORTANT » ou « YOU MUST » devant une instruction améliore son suivi, et Anthropic le recommande noir sur blanc pour les règles qui ne souffrent aucune exception. À utiliser avec parcimonie : si tout est important, plus rien ne l’est, et tu recrées le problème de dilution du fichier trop long. Le hip-hop connaît bien cette règle : quand chaque mesure crie, la punchline n’existe plus.

Il reste enfin une limite structurelle à connaître, parce qu’elle définit la frontière de l’outil : le CLAUDE.md est du contexte, pas de la configuration. Claude le lit et s’efforce de le suivre, sans garantie mécanique. Pour tout ce qui doit être bloqué à coup sûr, Claude Code propose les hooks, des scripts qui s’exécutent à des moments précis du cycle, quoi que le modèle décide. Le tableau suivant répartit les besoins entre les deux mécanismes.

La règle de partage tient en une phrase : le CLAUDE.md façonne les décisions, le hook les contraint. Un interdit vital écrit uniquement en markdown est un pari ; le même interdit doublé d’un hook est une certitude, et le fichier peut alors se contenter d’expliquer le pourquoi. Sur un interdit vital, on ne parie pas.

Deux garde-fous de processus : le point d’arrêt et l’auto-audit

Les règles vues jusqu’ici portent sur le contenu produit ; les plus rentables de toutes portent sur le processus de production lui-même. Deux garde-fous se détachent, et si ton CLAUDE.md ne devait contenir que deux règles, ce seraient celles-là. Le principe dépasse l’assistant de code : dans un workflow automatisé, un contrôle déterministe placé avant ou après le modèle joue le même rôle que le nœud Guardrails dans n8n.

Le premier est le point d’arrêt avant exécution. Sur toute tâche longue ou traversante, le fichier impose à l’assistant de produire d’abord un plan, puis de s’arrêter et d’attendre une validation explicite avant d’écrire la moindre ligne. L’arithmétique joue massivement en ta faveur : relire un plan coûte deux minutes, tandis qu’une exécution partie dans la mauvaise direction coûte l’heure de travail perdue, plus le nettoyage, plus la reformulation. Le point d’arrêt transforme l’erreur de cap la plus chère en correction la moins chère, et il t’évite le pire scénario du travail avec un agent : découvrir en fin de tâche que la question de départ avait été mal comprise. Ce garde-fou vaut pour le code comme pour tout le reste ; c’est exactement le mécanisme qui sépare une délégation contrôlée d’un vibe coding subi, où l’on accepte du code qu’on ne comprend plus.

Le second est la checklist d’auto-audit en fin de tâche. Le fichier exige que l’assistant termine chaque livraison en repassant une liste de contrôles observables, build, tests, interdits de style, complétude, et qu’il déclare honnêtement les points non conformes au lieu de les taire. L’effet est double. Pendant la tâche, la checklist agit en amont : sachant qu’il devra rendre des comptes point par point, l’assistant intègre les contraintes dès la production. Après la tâche, elle te donne un rapport structuré à vérifier, bien plus rapide à contrôler qu’une affirmation globale de réussite. La règle d’or : la checklist ne se coche que sur preuve, une sortie de commande, un résultat de recherche, jamais sur intention. Pas de preuve, pas de coche.

Ces deux garde-fous tournent tous les jours sur un projet bien réel, le blog que tu es en train de lire, et c’est le moment de regarder son moteur.

Cas d’étude : le CLAUDE.md et le prompt qui pilotent ce blog

Ce blog est rédigé avec Claude Code, encadré par deux fichiers : un CLAUDE.md à la racine du dépôt, qui fixe les règles permanentes du projet, et un fichier de prompt éditorial, chargé en complément, qui décrit le processus de rédaction d’un article. On assume la transparence, et elle tombe bien : ces fichiers appliquent chacune des techniques vues plus haut, sur un cas dont je peux citer les extraits exacts.

Première technique à l’œuvre, la contrainte avec condition d’arrêt. Le CLAUDE.md du projet contient cette règle, citée telle quelle :

**Regle absolue : ne rien inventer.** Aucun chiffre, aucun temoignage, aucun
nom, aucune fonctionnalite qui ne figure pas dans cette source. Si une
information manque, s'arreter et la demander.

Le point décisif est la seconde phrase. Interdire d’inventer ne suffit pas, parce qu’un modèle face à un trou d’information a une tentation naturelle : le combler avec quelque chose de plausible. La règle prescrit donc le comportement de remplacement, s’arrêter et demander, ce qui donne à l’interdit une porte de sortie concrète. Une bonne contrainte négative dit toujours quoi faire à la place.

Deuxième technique, la contrainte vérifiable par machine. Le fichier interdit un tic d’écriture typique des IA, la structure « ce n’est pas X, c’est Y », et il pousse l’interdit un cran plus loin : il fournit le motif de recherche qui prouve son absence, en imposant de « verifier avant livraison avec le motif regex “n’est pas … c’est” ». L’interdit de style devient un contrôle automatisable : un grep sur le fichier livré rend le verdict, sans débat d’interprétation. C’est la même logique de contrainte outillée qu’on retrouve dans les prompts d’un agent de rédaction SEO, où chaque exigence doit pouvoir se vérifier en aval.

Troisième technique, l’exemple négatif contextualisé. Cet extrait protège une décision produit :

**Pas de section tarifs.** JP l'a explicitement retiree du site Astro, meme si
elle existe en production. Ne pas la reintroduire sans demande.

Sans cette règle, la situation ressemble à un piège tendu à un assistant consciencieux : la section existe sur le site en production, elle manque dans le code, la conclusion logique serait de la « réparer ». La règle désamorce le piège en donnant la raison, un retrait volontaire, et transforme ce qui serait passé pour un oubli en décision documentée. Toute divergence voulue entre ton projet et ce à quoi il « devrait » ressembler mérite ce traitement, sans quoi elle sera corrigée un jour, avec les meilleures intentions du monde.

Quatrième technique, le point d’arrêt, inscrit dans le prompt éditorial au milieu du mode opératoire :

Produis un plan detaille (H2 et H3, avec en une ligne ce que contient chaque
section) et **arrete-toi**. Attends la validation. Ne redige pas.

Trois phrases courtes, dont deux redondantes à dessein : « arrête-toi », « attends la validation », « ne rédige pas » disent trois fois la même chose, parce que c’est la règle que la dynamique d’une session pousse le plus à enfreindre. En pratique, chaque article de ce blog, celui-ci compris, a commencé par un plan livré seul, corrigé ou validé avant qu’une ligne du corps soit écrite, et plusieurs plans ont été réorientés à ce stade, pour le coût de quelques minutes.

Cinquième technique, l’auto-audit : le processus impose de terminer chaque article par une checklist passée point par point dans un commentaire, en listant « honnêtement ce qui pèche », formulation du fichier. La liste couvre des contrôles observables, le build qui passe, l’absence de tirets cadratins vérifiée par recherche, le comptage de mots, les liens qui pointent tous vers des pages existantes. Quand un article livre 2 700 mots là où la cible en demandait 2 800, l’audit le dit, et c’est cette obligation d’honorer les écarts qui rend le reste de la checklist crédible.

Ce que le cas d’étude montre en creux mérite d’être souligné : presque rien dans ces fichiers ne décrit le projet. Pas de présentation d’Astro, pas de liste des dépendances, pas d’arborescence commentée au-delà du minimum. L’espace est occupé par des règles, des interdits munis de leur motif de vérification, des processus avec leurs points d’arrêt, et des faits que rien dans le code ne permet de retrouver, comme les chiffres exacts affichés sur le site. C’est la répartition cible d’un bon CLAUDE.md.

Garder son CLAUDE.md sous 200 lignes

Le système du cas d’étude tient dans deux fichiers de taille contenue, et cette sobriété se défend activement, parce qu’un fichier d’instructions ne connaît qu’une seule dérive naturelle : grossir. Chaque incident ajoute sa règle, personne n’en retire jamais, et six mois plus tard le fichier a rejoint le cimetière des CLAUDE.md décoratifs de la première section.

La documentation officielle fixe un cap chiffré : viser moins de 200 lignes par fichier. Au-delà, double peine, le fichier consomme du contexte utile à chaque session et l’adhérence aux règles baisse. Le symptôme est reconnaissable entre tous : Claude enfreint une règle qui figure pourtant dans le fichier. Le réflexe spontané, répéter la règle une ligne plus bas, aggrave le mal en allongeant encore le fichier ; le bon geste consiste presque toujours à supprimer dix lignes autour pour que la règle respire. Moins de lignes, plus d’autorité.

Pour démarrer sans partir d’une page blanche, la commande /init analyse ton dépôt, détecte les commandes de build et de test, repère les conventions visibles et génère une première version, qu’elle propose d’améliorer si un fichier existe déjà. Prends cette base pour ce qu’elle est : un inventaire de ce que le code montre. Tout ce qui fait la valeur du fichier, tes interdits, tes divergences assumées, ta définition du terminé, n’y figure pas encore, puisque justement le code ne le montre pas.

Quand le contenu légitime dépasse le cap des 200 lignes, la solution s’appelle découpage, avec une nuance qui compte. Les imports @fichier organisent le contenu en modules mais chargent tout au lancement : ils clarifient la maintenance sans économiser un seul token. Les règles de .claude/rules/ avec un frontmatter paths, elles, ne se chargent que lorsque la session touche aux fichiers correspondants : c’est le seul découpage qui allège réellement le contexte. Concrètement, les règles d’API partent dans un fichier limité à src/api/**, celles des tests dans un autre limité à **/*.test.ts, et le CLAUDE.md racine ne garde que le transversal.

Reste l’entretien, et il se résume à une boucle : chaque erreur répétée de l’assistant devient une ligne du fichier, chaque ligne sans effet observable saute. Pour tester qu’une règle a un effet, un seul juge de paix, la session réelle. La grille suivante donne la méthode, règle par règle : provoquer la situation, observer le comportement.

Si le comportement attendu se produit sans qu’on le rappelle, la règle vit ; s’il faut la répéter en session, elle est soit mal formulée, soit noyée, et dans les deux cas c’est le fichier qu’on corrige, jamais la conversation. Un CLAUDE.md se travaille exactement comme du code : il se relit quand quelque chose casse, il se taille régulièrement, et chaque modification se valide en observant si le comportement change vraiment. Écrit ainsi, ligne après ligne gagnée sur l’usage, le fichier devient ce qu’aucune session ne peut être : la mémoire de tout ce que ton projet a appris en travaillant avec une IA.