Comment bien écrire ton fichier CLAUDE.md
- Le CLAUDE.md est un simple fichier texte que Claude Code lit au début de chaque session : tu y mets seulement ce qu'il ne peut pas deviner en lisant ton projet.
- Vise moins de 200 lignes, des consignes qu'on peut vérifier, rangées sous des titres, et aucune contradiction.
- Ce qui ne concerne qu'une partie du projet part dans .claude/rules, une procédure longue dans un skill, une règle sans exception dans un hook.
- Vérifie qu'il est chargé avec /context all et fais-le relire de temps en temps avec /doctor prompt-audit.
Un bon fichier CLAUDE.md, c'est un fichier court (moins de 200 lignes) qui dit à Claude Code ce qu'il ne peut pas trouver tout seul en lisant ton projet : les commandes pour vérifier son travail, les pièges, les décisions prises ailleurs et tout ce que tu as déjà dû corriger 2 fois. Chaque consigne doit être assez précise pour se vérifier, genre « lance npm test avant de dire que c'est fini » plutôt que « teste bien ». Le reste (la liste de tes dossiers, les généralités, les procédures longues) n'a rien à faire dedans.
Je ne code plus mes outils, mes agents IA le font pour moi. Chaque activité a son OS (Brunelia, Quel Canapé, ma newsletter, ma compta...), et chaque agent, à la base, c'est une conversation Claude Code qui tourne dans un terminal. Le truc c'est que chaque session de Claude Code démarre avec un contexte vide. Le CLAUDE.md, c'est ce qui évite de tout réexpliquer à chaque fois.
Dans ce guide je te montre où le ranger, quoi écrire, ce qu'il faut sortir du fichier, quand passer à un hook, et un exemple complet pour un projet qui n'est même pas du code. Presque toutes les pages de Google parlent à des développeurs. Moi je pense que le CLAUDE.md est encore plus utile quand tu n'en es pas un (si tu débutes, commence par mes guides Claude Code).
Tu en es où ?
Le CLAUDE.md, c'est quoi exactement
Le CLAUDE.md est un fichier au format Markdown, c'est-à-dire du texte brut avec quelques symboles de mise en forme : # pour un titre, - pour une puce. Tu l'écris en français normal, pas en code. Claude Code le lit au début de chaque session et le garde sous les yeux pendant tout le travail.
Le point que presque personne n'explique : d'après la documentation d'Anthropic, le contenu du CLAUDE.md arrive comme un message utilisateur placé juste après les consignes système de Claude Code. Ce n'est pas une configuration imposée. Claude le lit et essaie de le suivre, sans obligation stricte, surtout si la consigne est floue ou contredite ailleurs.
Concrètement, ça change ta façon d'écrire. Tu n'écris pas un règlement, tu mets au courant un collègue très doué qui débarque chaque matin sans aucun souvenir de la veille. Ce qu'il doit savoir dès la 1re minute va dans le fichier, le reste il le trouvera en lisant le projet.
À ne pas confondre avec la mémoire automatique. Claude Code prend aussi ses propres notes (tes préférences, tes corrections) dans un dossier à part, avec un index MEMORY.md dont seules les 200 premières lignes ou les 25 premiers Ko sont chargées à chaque session. Le CLAUDE.md, c'est toi qui l'écris. La mémoire automatique, c'est Claude. Je détaille ce qu'il retient d'une session à l'autre dans un guide à part.
| CLAUDE.md | Mémoire automatique | |
|---|---|---|
| Qui l'écrit | Toi | Claude |
| Ce qu'il contient | Tes consignes et tes règles | Ce que Claude a appris de tes corrections |
| Ce qui est chargé | Le fichier en entier, à chaque session | Les 200 premières lignes ou 25 Ko de l'index |
| Portée | Organisation, utilisateur ou projet | Un dépôt, sur ta machine seulement |
Où ranger ton CLAUDE.md : les 4 emplacements
Il n'y a pas un CLAUDE.md, il peut y en avoir à 4 niveaux, chargés du plus large au plus précis. Ils ne s'écrasent pas entre eux : Claude Code les met bout à bout, et ce qui est le plus proche de ton dossier de travail est lu en dernier.
Petite subtilité : si tu lances Claude Code dans un sous-dossier, il charge aussi les CLAUDE.md des dossiers au-dessus. Les CLAUDE.md rangés plus bas, dans des sous-dossiers, ne se chargent qu'au moment où Claude lit ou modifie un fichier de ce sous-dossier.
Pour savoir ce qui est vraiment chargé, tape /context all dans une session et regarde la liste Memory files. Si ton fichier n'y est pas, Claude ne le voit pas, point. /memory te montre aussi tous les emplacements et t'ouvre le fichier choisi dans ton éditeur.
La règle simple : ce qui doit te suivre partout va dans le fichier utilisateur, genre « réponds-moi en français ». Ce qui concerne un projet précis va dans le fichier du projet. Je détaille ce partage dans le guide CLAUDE.md global ou CLAUDE.md du projet : que mettre où. Voici les 4 emplacements, du plus large au plus précis :
- Organisation : un fichier posé par le service informatique (sur Mac, dans /Library/Application Support/ClaudeCode/), valable pour tout le monde sur la machine.
- Utilisateur : ~/.claude/CLAUDE.md, tes préférences perso pour tous tes projets.
- Projet : ./CLAUDE.md ou ./.claude/CLAUDE.md, partagé avec ton équipe via Git, le logiciel qui garde l'historique des fichiers.
- Local : ./CLAUDE.local.md, tes préférences pour ce projet seulement, à ajouter au fichier .gitignore pour qu'il ne parte jamais dans le dépôt.
Ce qui va dedans, et ce qui n'y a pas sa place
Le test à appliquer ligne par ligne : est-ce que Claude pourrait le trouver tout seul en lisant le projet ? Si oui, la ligne dégage. Anthropic le rappelle dans ses bonnes pratiques : chaque ligne du fichier prend un peu de l'attention de Claude sur chaque tâche, même quand elle ne sert à rien.
Ce qui n'a rien à y faire : la description de tes dossiers (Claude lit le projet tout seul), les règles génériques qu'il connaît déjà comme « écris du code propre », les procédures en 15 étapes et surtout tes secrets. Une procédure longue va dans un skill, une fiche de procédure que Claude ne lit en entier que quand la tâche le demande. Une clé d'accès ou un mot de passe n'a rien à faire dans un fichier partagé.
Dans la liste juste en dessous, la ligne qui compte le plus pour moi, c'est la dernière, parce qu'elle rejoint une leçon de mon Carnet. Le 19 octobre, j'ai corrigé le même bogue 6 fois, sur 6 OS différents, le même jour. Ce n'était pas 6 bogues, c'était 1 seul mal rangé : chaque OS gérait ses propres comptes IA dans son coin. J'ai tout centralisé dans un coffre unique que chaque OS consulte d'abord. Pour le CLAUDE.md c'est pareil : si tu tapes la même correction 2 sessions de suite, c'est qu'elle doit être écrite à un endroit que Claude lit à chaque fois.
Ce qui mérite sa place, d'après les bonnes pratiques d'Anthropic :
- Les commandes pour vérifier le travail : lancer les tests, contrôler le code, tester un seul fichier.
- Les endroits trompeurs : un vieux dossier encore utilisé qu'il ne faut pas copier, un fichier qui a l'air abandonné mais qui sert encore.
- Les décisions prises hors du projet : comment on met en ligne, quel outil l'équipe a choisi, ce qui demande une relecture humaine.
- Tout ce que tu as déjà dû corriger 2 fois.
Écrire des consignes que Claude suit vraiment
1re règle : une consigne doit pouvoir se vérifier. « Formate bien le code » ne dit rien. « Indentation de 2 espaces » se contrôle d'un coup d'œil. Pareil pour « teste tes changements » contre « lance npm test avant chaque commit » (un commit, c'est un enregistrement de tes modifications dans Git).
2e règle : range tout sous des titres Markdown et des puces. Des sections courtes se suivent mieux qu'un gros pavé. Je te conseille de partir de 3 titres simples, Commandes, Conventions et Pièges, et de n'en ajouter un que quand une rubrique déborde.
3e règle : aucune contradiction. Si une ligne dit « réponds court » et une autre « explique toujours en détail », Claude peut choisir l'une ou l'autre au hasard. C'est encore plus sournois quand la contradiction est entre 2 fichiers, ton CLAUDE.md utilisateur et celui du projet par exemple.
Et la 4e, qui surprend : arrête les MAJUSCULES et les IMPORTANT. Anthropic l'écrit dans ses bonnes pratiques : les modèles actuels suivent une consigne écrite simplement, et en rajouter pousse surtout Claude à appliquer la règle partout, même là où elle n'a pas de sens. Si une ligne est ignorée, c'est soit que le fichier est trop long, soit que la règle devrait être un hook.
Dans Made to Stick, Chip et Dan Heath racontent l'expérience des tapeurs : une personne tape du doigt le rythme d'une chanson connue sur une table, l'autre doit trouver le titre. Le tapeur entend la mélodie dans sa tête et trouve ça évident, l'auditeur n'entend que des coups secs et ne trouve presque jamais. Ils appellent ça la malédiction du savoir. Ton CLAUDE.md, c'est exactement ça : toi tu connais tout le contexte, Claude n'entend que les coups. Écris pour quelqu'un qui n'a jamais vu ton projet, avec des chemins, des commandes et des exemples.
| Consigne floue | Consigne vérifiable |
|---|---|
| Formate bien le code | Indentation de 2 espaces |
| Teste tes changements | Lance npm test avant chaque commit |
| Range bien les fichiers | Les routes de l'API vont dans src/api/handlers/ |
| Écris des mails sympas | Tutoie le lecteur, 1 seul lien par mail |
Ton fichier déborde ? 3 façons de le garder sous 200 lignes
Anthropic donne un repère clair : moins de 200 lignes par CLAUDE.md. Au-delà, le fichier prend plus de place dans le contexte (tout ce que Claude a sous les yeux pendant la session) et il est moins bien suivi. Claude Code affiche même un avertissement au démarrage, et dans /status, quand un fichier dépasse la longueur conseillée.
Quand ça déborde, tu as 3 sorties, et elles ne se valent pas. La 1re, ce sont les imports avec @ : tu écris @docs/conventions.md dans ton CLAUDE.md et ce fichier est chargé avec lui, jusqu'à 4 niveaux d'imports en chaîne. Pratique pour ranger, mais ça ne fait rien gagner, puisque le fichier importé est chargé en même temps.
La 2e, c'est le dossier .claude/rules : un fichier par sujet (tests.md, style.md...). Avec un champ paths en tête de fichier, la règle ne se charge que quand Claude touche les fichiers concernés. Là, tu gagnes vraiment de la place. Exemple de règle limitée à une partie du projet, à poser dans .claude/rules/api.md : ```markdown --- paths: - "src/api/**/*.ts" --- # Règles de l'API - Chaque route vérifie les données reçues - Les erreurs suivent le format de src/lib/errors.ts ```
La 3e, ce sont les skills, pour une procédure longue (mettre en ligne, publier un article) : Claude ne voit que leur nom et leur description, et lit le reste seulement quand la tâche le demande.
Dernière astuce, rarement expliquée : les commentaires HTML, écrits entre <!-- et -->, sont retirés avant que le fichier soit envoyé à Claude. Tu peux donc laisser des notes pour les humains (pourquoi telle règle existe, qui l'a ajoutée) sans dépenser une ligne de contexte.
Je détaille ces 3 sorties dans des guides dédiés : la taille à garder quand ton CLAUDE.md devient trop long, l'import d'autres fichiers avec @, et le rangement de tes consignes par sujet dans le dossier .claude/rules.
Quand une consigne ne suffit pas : passer au hook
C'est le passage qu'on lit rarement, et c'est pourtant celui qui compte le plus quand tes agents tournent sans toi. Un CLAUDE.md, c'est une ligne directrice : Claude a le droit de décider qu'elle ne s'applique pas à la situation. Pour la plupart des consignes, c'est très bien comme ça.
Mais certaines règles ne supportent aucune exception : ne jamais lire le fichier .env (celui où dorment tes mots de passe), ne jamais toucher au dossier des migrations, toujours lancer le formatage après une modification. Pour celles-là, Anthropic recommande de sortir la règle du CLAUDE.md et d'en faire un hook, c'est-à-dire une commande qui s'exécute automatiquement à un moment précis (avant une action, après une modification), ou une règle de refus dans les réglages. Le résultat ne dépend plus de ce que Claude se rappelle ou décide.
Tu n'as même pas à l'écrire toi-même : demande « écris un hook qui bloque les modifications du dossier migrations », Claude le fait, et /hooks te montre le résultat. Par contre, n'en abuse pas. « Préfère les exports nommés » a plein d'exceptions, ça reste dans le CLAUDE.md.
Dans Work the System, Sam Carpenter raconte comment il a sorti son entreprise de permanence téléphonique du chaos en écrivant 3 types de documents : un objectif stratégique, des principes de fonctionnement, puis des procédures de travail détaillées. Je retrouve exactement ce découpage dans Claude Code. Le CLAUDE.md porte les principes, les skills portent les procédures, et le hook, c'est la procédure qu'on ne laisse plus au choix de personne.
Chez moi, c'est le même raisonnement qui m'a servi sur Pinterest OS. Plutôt que d'espérer que tout se passe bien, j'ai fait en sorte que les textes soient enregistrés dès qu'ils sont rédigés, pour ne pas tout perdre à cause d'une image ratée. Ce qui ne doit pas casser, je ne le laisse pas à la bonne volonté de l'agent.
Tester, partager et faire vivre ton fichier
Pour démarrer, pas besoin d'une page blanche : tape /init dans Claude Code. Il analyse ton projet et propose un 1er CLAUDE.md avec les commandes et les conventions qu'il a repérées. S'il existe déjà un fichier, /init propose des améliorations au lieu de l'écraser. Après, d'après Anthropic, le gros du travail consiste surtout à enlever des lignes.
Ensuite, traite-le comme du code : il vit dans Git et évolue avec le projet. Le CLAUDE.md du projet se partage avec ton équipe via le dépôt, et chacun garde ses réglages perso dans son CLAUDE.local.md. Si ton projet a déjà un AGENTS.md (le même genre de fichier, lu par d'autres assistants de code), Claude Code sait le lire quand il n'y a aucun CLAUDE.md ni CLAUDE.local.md dans ton dossier ou au-dessus. Attention au piège : créer un CLAUDE.local.md dans un projet qui repose sur AGENTS.md suffit pour que Claude ne lise plus AGENTS.md. Tu peux aussi écrire @AGENTS.md dans ton CLAUDE.md pour n'avoir qu'une seule source. Je développe tout ça dans le guide Partager un CLAUDE.md avec son équipe.
Une fois par mois, je te conseille de lancer /doctor prompt-audit. Claude cherche les consignes écrites pour d'anciens modèles, les fichiers ou commandes cités qui n'existent plus et les contradictions entre fichiers, puis te propose des corrections. Rien ne bouge tant que tu ne valides pas.
Dans The E-Myth Revisited, Michael Gerber pousse les entrepreneurs à construire leur boîte comme si elle allait être franchisée : tout doit être écrit pour que quelqu'un d'autre puisse la faire tourner sans toi. Son fil rouge, c'est Sarah et sa boutique de tartes, prisonnière de son propre savoir-faire parce que rien n'est écrit. Ton CLAUDE.md, c'est le 1er document de cette franchise : ce qui n'est écrit nulle part reste dans ta tête, et ta tête ne tourne pas la nuit.
Pour aller plus loin, tu trouveras le reste de mes tutos dans l'IA et l'automatisation, et les outils que j'utilise au quotidien dans la Boîte à outils.
Pour écrire et tester ton CLAUDE.md, il te faut un accès à Claude Code : si tu n'en as pas encore, tu peux découvrir Claude Pro, qui inclut Claude Code. Je te conseille de vérifier d'abord ton compte actuel et les limites du forfait ; si tu as déjà accès à Claude Code, tu n'as rien à prendre en plus.
Exemple fictif : le CLAUDE.md d'une newsletter préparée avec Claude Code
- Le contexte (fictif) : tu prépares une newsletter chaque semaine dans un dossier newsletter/, avec Claude Code pour écrire les brouillons. Et chaque semaine, tu répètes les 4 mêmes corrections.
- Tu lances /init. Claude crée un 1er fichier de 60 lignes, dont 35 décrivent les dossiers du projet.
- Tu supprimes la description des dossiers, puisque Claude la lit tout seul : il reste 25 lignes, dont la commande d'aperçu repérée par /init.
- Tu ajoutes tes 4 corrections répétées, une par ligne, sous 3 titres : ```markdown # Commandes - Aperçu d'un numéro : npm run apercu -- numeros/AAAA-MM-JJ.md # Conventions - Tutoiement, phrases de 20 mots maximum - 1 seul lien principal par numéro, placé avant la signature - Les brouillons vont dans brouillons/, jamais dans numeros/ # Pièges - Le dossier archives/ est en lecture seule : ne rien y modifier ```
- Tu passes « ne rien modifier dans archives/ » en hook, parce que c'est une règle à 0 exception, et tu retires la ligne du fichier.
- Tu vérifies avec /context all que le fichier apparaît bien dans Memory files, puis tu lances une vraie demande de brouillon pour voir s'il suit les consignes.
Résultat : un fichier d'une trentaine de lignes où chaque ligne vient d'une correction réelle, contre 60 lignes génériques au départ. Le gain ne se voit pas le 1er jour. Il se voit au 10e numéro, quand tu n'as plus rien à répéter.
Les erreurs fréquentes
Ta check-list
Tout le guide en une image
Pour aller plus loin
J'ai automatisé tout mon business avec Claude Code (8 étapes)Vidéo de 27 minMa chaîne YouTube ›Questions fréquentes
Quel format de fichier pour CLAUDE.md ?
Du Markdown, donc du texte simple : # pour les titres, - pour les puces, des blocs de code entre 3 accents graves si tu veux montrer une commande. Le nom exact compte : CLAUDE.md, à la racine du projet ou dans le dossier .claude/.
Quelle est la taille maximale d'un fichier CLAUDE.md ?
Anthropic conseille de rester sous 200 lignes par fichier pour qu'il soit bien suivi. Techniquement, un CLAUDE.md chargé au démarrage est lu en entier jusqu'à 4 Mio, et ignoré au-delà. Ceux des sous-dossiers ont une limite plus basse : au-delà, Claude n'en reçoit que le début. Ne confonds pas avec l'index MEMORY.md de la mémoire automatique, lui limité à 200 lignes ou 25 Ko chargés.
Quelles sont les meilleures instructions à mettre dans CLAUDE.md ?
Celles que Claude ne peut pas trouver seul : les commandes pour vérifier son travail, les pièges du projet, les décisions prises ailleurs et les corrections que tu as déjà faites 2 fois. Chaque ligne doit pouvoir se vérifier.
Peut-on utiliser le même CLAUDE.md pour plusieurs projets ?
Oui, contrairement à ce qu'on lit parfois. Le fichier ~/.claude/CLAUDE.md s'applique à tous tes projets, et le dossier ~/.claude/rules aussi. Tu peux aussi relier un dossier de règles partagé avec un lien symbolique dans .claude/rules : s'il pointe hors du projet, Claude Code te demande ton accord une fois, puis ne charge que les règles sans champ paths.
Faut-il écrire son CLAUDE.md en anglais ?
Rien dans la documentation ne l'impose : Anthropic demande seulement des consignes précises en langage naturel, et Claude comprend très bien le français. Garde juste les noms de commandes, de fichiers et de dossiers exactement comme ils sont écrits dans ton projet.
Quelle différence entre CLAUDE.md et AGENTS.md ?
C'est le même rôle : AGENTS.md est le nom utilisé par d'autres assistants de code. Claude Code lit AGENTS.md seulement s'il ne trouve aucun CLAUDE.md ni CLAUDE.local.md dans ton dossier ou au-dessus. Pour garder les 2, écris @AGENTS.md dans ton CLAUDE.md, et tout est chargé ensemble.
Comment savoir si Claude a bien lu mon CLAUDE.md ?
Tape /context all dans une session et regarde la liste Memory files. Un CLAUDE.md rangé dans un sous-dossier n'y apparaît pas au démarrage, c'est normal : il se charge quand Claude touche un fichier de ce sous-dossier.
Sources
- CLAUDE.md : 4 emplacements (organisation, utilisateur ~/.claude/CLAUDE.md, projet ./CLAUDE.md ou ./.claude/CLAUDE.md, local ./CLAUDE.local.md à mettre dans .gitignore), concaténés du plus large au plus précis ; sous-dossiers chargés à la demande ; contenu livré comme message utilisateur après le prompt système ; chaque session démarre avec un contexte vide ; emplacement organisation sur macOS dans /Library/Application Support/ClaudeCode/ ; avertissement au démarrage et dans /status au-delà de la longueur conseillée ; /init propose des améliorations sans écraser un fichier existant ; /doctor prompt-audit ne modifie rien tant qu'on ne demande pas d'appliquer ; CLAUDE.md de sous-dossiers et règles à la demande soumis à une limite par fichier plus basse ; un CLAUDE.local.md empêche la lecture d'AGENTS.md ; lien symbolique hors du projet soumis à accord, seules les règles sans paths chargées ; viser moins de 200 lignes par fichier ; imports @ jusqu'à 4 niveaux qui ne réduisent pas le contexte ; .claude/rules avec champ paths ; commentaires HTML retirés ; fichier de plus de 4 Mio ignoré ; MEMORY.md chargé sur 200 lignes ou 25 Ko ; /context all, /memory, /init, /doctor prompt-audit ; AGENTS.md lu en l'absence de CLAUDE.md ; ~/.claude/rules et liens symboliques pour partager des règles. : https://code.claude.com/docs/en/memory (consulté le 2026-11-11)
- Bonnes pratiques : garder CLAUDE.md court avec les commandes de vérification, les endroits trompeurs, les décisions absentes du dépôt et ce qui a été corrigé 2 fois ; ne pas décrire l'architecture ; IMPORTANT et majuscules déconseillés avec les modèles actuels ; règles sans exception en hook ou règle de refus ; /hooks ; skills lus en entier seulement quand la tâche le demande ; /init puis surtout retirer des lignes ; CLAUDE.local.md pour les préférences perso. : https://code.claude.com/docs/en/best-practices (consulté le 2026-11-11)
- Les hooks exécutent des commandes à des moments fixes du travail de Claude Code (par exemple avant l'utilisation d'un outil) et s'appliquent quoi que Claude décide. : https://code.claude.com/docs/en/hooks-guide (consulté le 2026-11-11)
Autres pages sur notre guide « Claude Code »
Toutes les pages du sujet sont dans notre guide « Claude Code ».