Chaque session de Claude Code démarre avec une fenêtre de contexte vide. Le fichier CLAUDE.md est ce qui fait passer vos conventions d’une session à la suivante.
C’est le fichier qui fait le plus de travail dans un dépôt où l’IA code. Il a aussi une limite précise, qu’Anthropic écrit noir sur blanc. Elle change la façon de s’en servir.
La limite, tout de suite
La documentation l’écrit en toutes lettres. Claude traite ces fichiers comme du contexte, pas comme une configuration appliquée.
Et elle ajoute la conséquence. Pour bloquer une action quelle que soit la décision de Claude, il faut un hook PreToolUse.
Plus loin, elle est encore plus nette. Le contenu du CLAUDE.md arrive comme un message utilisateur après le prompt système. Claude le lit et essaie de le suivre, sans garantie de conformité stricte. Surtout sur des consignes vagues ou contradictoires.
Une équipe peut écrire « toujours lancer les tests » en gras et en majuscules. Elle verra quand même passer des commits sans tests. Ce n’est pas un bug. C’est la nature du fichier, et le remède est ailleurs, dans les hooks.
Ce qu’on y met
La documentation donne un critère simple. Le CLAUDE.md est l’endroit où l’on écrit ce qu’on devrait sinon réexpliquer.
Quatre déclencheurs, qu’elle liste. Claude fait la même erreur une deuxième fois. Une revue de code attrape quelque chose qu’il aurait dû savoir sur ce dépôt. Vous tapez dans le chat la correction que vous tapiez déjà la session d’avant. Un nouvel arrivant aurait besoin du même contexte pour être utile.
Le contenu visé, ce sont les faits que Claude doit avoir à chaque session. Commandes de build, conventions, plan du projet, règles du type « toujours faire X ».
Et ce qui n’y va pas. Une procédure en plusieurs étapes, ou une consigne qui ne concerne qu’une partie du dépôt. Chacune va dans un skill ou dans une règle par chemin.
Les quatre emplacements
Ils se chargent du plus large au plus précis. Une consigne de projet arrive donc après une consigne personnelle.
Le fichier géré par l’organisation, qu’on ne peut pas exclure. Le ~/.claude/CLAUDE.md, vos préférences sur tous vos projets. Le CLAUDE.md du projet, partagé par le dépôt, qui est celui qui compte pour une équipe. Le CLAUDE.local.md, personnel au projet. Je le mets dans le .gitignore.
Un point de mécanique utile. Tous les fichiers trouvés sont mis bout à bout, ils ne s’écrasent pas. Et dans chaque dossier, le fichier local est ajouté après le partagé.
Un cas à connaître si votre dépôt vient d’un autre outil. Par défaut, Claude lit un AGENTS.md quand vous n’avez aucun CLAUDE.md dans votre dossier de travail ni au-dessus. Votre ~/.claude/CLAUDE.md, le fichier géré par l’organisation et les règles de .claude/rules/ ne comptent pas dans ce test. Le réglage Project instructions permet de lire les deux.
La taille, et le seuil chiffré
Moins de 200 lignes par fichier. La documentation le pose comme cible et en donne la raison. Un fichier plus long consomme plus de contexte et réduit le suivi des consignes.
Le plafond dur est ailleurs. Claude Code charge un fichier jusqu’à 4 Mio en entier et ignore un fichier plus gros.
Et un point de mécanique qui compte au moment de découper. Les imports @chemin aident l’organisation et ne réduisent pas le contexte. Les fichiers importés se chargent aussi au démarrage.
La vraie solution au fichier qui gonfle, ce sont les règles par chemin.
Les règles par chemin, pour un gros dépôt
Dans .claude/rules/, un fichier par sujet. Une règle sans champ paths se charge toujours. Une règle avec paths ne se charge que lorsque Claude travaille sur des fichiers correspondants.
C’est ce qui permet à un gros dépôt de garder des consignes précises. Elles ne sont plus chargées à chaque session.
Un détail à connaître avant d’y passer du temps. paths est le seul champ que Claude Code lit dans une règle. Tout autre champ est ignoré, sans erreur.
Écrire des consignes qui tiennent
Deux critères, et la documentation en donne des exemples.
Concret plutôt que général. « Utiliser une indentation de deux espaces » plutôt que « formater le code correctement ». « Lancer npm test avant de committer » plutôt que « tester vos changements ». « Les handlers d’API vivent dans src/api/handlers/ » plutôt que « garder les fichiers organisés ».
Cohérent. Si deux règles se contredisent, Claude peut en choisir une arbitrairement. Sur un fichier d’équipe qui grossit pendant un an, c’est le risque qui revient.
La commande /doctor prompt-audit existe pour ça. Elle cherche les consignes écrites pour des modèles anciens. Les références à des fichiers disparus. Et les fichiers qui se contredisent.
La mémoire automatique, l’autre mécanisme
Le CLAUDE.md est écrit par vous. La mémoire automatique est écrite par Claude, à partir de vos corrections et de vos préférences.
Les 200 premières lignes de son fichier MEMORY.md, ou les 25 premiers kilooctets, se chargent à chaque conversation.
Pour une équipe, la distinction à garder est celle-ci. Ce qui doit être partagé et relu par des humains va dans le CLAUDE.md du dépôt. Ce que Claude apprend de vos habitudes reste sur votre machine.
Les trois commandes à connaître
/init génère un premier CLAUDE.md en analysant votre dépôt. Si un fichier existe déjà, il propose des améliorations au lieu de l’écraser.
/context liste les fichiers de mémoire que la session a chargés. Si le vôtre n’y figure pas, il n’est pas chargé. C’est le premier réflexe de diagnostic.
/memory liste les fichiers, les ouvre et porte l’interrupteur de la mémoire automatique.
Ce que ça change pour une équipe
Un CLAUDE.md de projet est la façon la plus simple d’obtenir les mêmes réponses dans toute l’équipe.
Le CLAUDE.md à la racine du projet survit d’ailleurs à la compaction. Après un /compact, Claude le relit sur disque et le réinjecte dans la session.
C’est le premier livrable d’une formation Claude Code chez un client. Le fichier est écrit en séance, sur le vrai dépôt. On part des corrections que l’équipe tape déjà.
La logique d’ensemble, pourquoi ce qui entre dans le contexte se choisit, est traitée dans context engineering. Et la façon dont plusieurs personnes ou plusieurs agents s’en servent est dans Claude Code en équipe.
Source relevée le 29 septembre 2026, la documentation de la mémoire d’Anthropic.