CLAUDE.md : le projet qui se souvient

Troisième session de la semaine, et tu retapes la phrase de lundi : non, pas cette bibliothèque-là ; les dates s’écrivent dans l’autre format ; ce dossier, on n’y touche pas. Ça marche à chaque fois — c’est exactement le problème. Ça marche, donc tu recommences demain.

Et le jour où tu oublies de la retaper, rien ne te prévient. Le travail sort avec l’ancienne convention, et tu le découvres à l’écran, deux jours plus tard.

Cette leçon propose de sortir la consigne de la conversation, et il faut dire tout de suite ce que ça échange, sinon la suite ressemble à une promesse. Écrire la consigne dans un fichier ne la rend pas obligatoire : tu troques un rappel manuel bruyant contre une consigne silencieuse. Le rappel manuel avait un mérite — tant que tu le retapais, tu savais qu’il était là ; une fois écrit, plus rien ne te dit qu’il est encore suivi. Deux conséquences, à poser avant le reste :

ce qui doit arriver à chaque fois, sans exception, ne s’écrit pas dans un fichier de règles. C’est la ligne du hook, un déclenchement automatique attaché à un événement, et c’est la leçon 5 qui donne le tableau ;
le reste (conventions, préférences, architecture) se range dans le fichier, et se vérifie. La moitié de cette leçon porte sur le rangement ; l’autre, sur les gestes qui disent si ce qui est rangé est encore vrai.

Ce qui se passe vraiment

Une session neuve ne sait rien de la précédente. La leçon 3 a posé pourquoi : chaque session démarre avec un plan de travail vierge. Deux mécanismes seulement portent une connaissance d’une session à la suivante :

les instructions que tu écris : le CLAUDE.md (le fichier de règles du projet, relu à chaque session) et sa famille, les fichiers du même nom posés dans des sous-dossiers, ceux qu’il importe, et les rules rangées dans .claude/rules/ (des fichiers d’instructions séparés, qu’on peut n’activer que pour certains fichiers). Un seul mécanisme : c’est toi qui l’écris, et c’est du texte relu au démarrage ;
les notes que Claude s’écrit à lui-même, c’est-à-dire la mémoire automatique (auto memory dans la documentation) : tes corrections, tes préférences, les régularités qu’il remarque.

Tout le reste est à redonner, ou à rouvrir en reprenant une session, ce qui est le sujet de la leçon 7.

L’image à garder pour le premier, c’est le mot punaisé au-dessus de l’établi : relu chaque matin, et contraint par sa forme — c’est un ordre, pas une explication, et personne ne punaise trois pages au-dessus de son établi. Le second, c’est le carnet que Claude garde dans sa poche : il ne sort pas de ta machine, et tu peux l’ouvrir quand tu veux. Le geste est plus bas.

Deux mécanismes, et ils ne se remplacent pas

	CLAUDE.md	Mémoire automatique
Qui l’écrit	toi	Claude
Ce qu’on y trouve	des instructions et des règles	des apprentissages et des régularités
Portée	le projet, ton compte, ou ton organisation	un dépôt, partagée entre ses worktrees (des répertoires de travail séparés du même dépôt, chacun avec ses fichiers et sa branche — leçon 14)
Chargement	à chaque session, en entier	à chaque session, mais seulement les 200 premières lignes ou 25 Ko de son fichier d’index
Ce que ça sert à porter	conventions de code, façons de travailler, architecture	commandes de build, trouvailles de débogage, préférences qu’il découvre

La mémoire automatique n’est pas un fichier, c’est un dossier : un index, MEMORY.md, chargé au début de chaque conversation, et des fichiers thématiques que Claude crée lui-même et va lire à la demande. Dire « le fichier de mémoire » écrase la moitié du mécanisme.

Et le même chiffre revient dans les deux colonnes sans avoir le même sens :

pour le CLAUDE.md, 200 lignes est une cible : il est chargé en entier quelle que soit sa longueur, mais au-delà il « consomme plus de contexte et réduit l’adhérence » — rien n’est coupé, tout est simplement moins suivi ;
pour l’index de la mémoire automatique, c’est un couperet : les 200 premières lignes ou les 25 premiers kilo-octets, au premier atteint. Ce qui dépasse n’entre pas.

Ce qui décide qu’une instruction est suivie, et ce qui la dégrade

Un fichier de règles n’est pas un investissement qu’on fait une fois. Quatre facteurs documentés décident si une instruction est suivie, et on peut les rater tous les quatre en écrivant vite : la précision, une instruction assez vague pour être comprise de plusieurs façons ; la structure, des paragraphes denses là où des sections et des puces se lisent mieux ; la taille, un fichier devenu assez long pour que chaque règle reçoive moins d’attention ; et la cohérence, deux fichiers qui donnent des directions contradictoires.

Une cinquième cause n’a besoin de personne : le modèle change. Une règle écrite pour contourner la limite d’un modèle plus ancien devient du bruit quand le suivant n’a plus cette limite, et ce bruit dilue les règles qui comptent — c’est la seule qui se dégrade toute seule.

La quatrième est la plus vicieuse, parce qu’elle ne ressemble pas à une panne : quand deux règles se contredisent, la documentation dit que Claude peut en choisir une arbitrairement. Pas d’erreur reproductible, donc, mais un comportement qui change d’un jour à l’autre — et tu chercheras la cause partout sauf dans ton propre fichier.

Ce que la divergence coûte, sur un vrai projet

En juillet 2026, j’ai audité un système d’alerte pour écoles en production : une application mobile, un serveur, deux dépôts. Le rapport range trois défauts sous le même constat — une information existe à deux endroits, les deux versions divergent, personne ne s’en aperçoit :

les jours de la semaine numérotés à partir du lundi côté téléphone, à partir du dimanche côté serveur : tout décalé d’un cran, et une alerte refusée le mardi ;
les codes de secours de la double authentification enregistrés sous une forme et comparés sous une autre : refusés à tous les coups ;
les libellés d’alerte rangés dans une table prévue pour ça, puis réécrits en dur à deux autres endroits qui ignorent la table.

Aucun n’était une faute de frappe. C’étaient des vérités qui avaient cessé de l’être à un endroit sans que l’autre l’apprenne. Et il faut dire ce que le rapport en conclut, parce que ce n’est pas « range mieux tes fichiers » : ce qui aurait attrapé ces défauts, c’est trois tests, une journée de travail. Le rangement réduit le nombre d’endroits où une vérité peut diverger ; il ne prévient personne quand elle diverge quand même.

À retenir — le savoir vit à un endroit. Une règle écrite à la fois dans ton fichier et dans ton code finira par exister en deux versions, et la fausse ne s’annoncera pas. Ce n’est pas une question de rangement : c’est ce qui décide si ton fichier vieillit bien ou s’il devient un piège de plus.

Ce qu’on fait

Rien à installer : un fichier texte. Où le poser, ce qu’on y écrit, ce qu’on en sort quand il grossit, et les gestes qui disent s’il est encore chargé et encore vrai.

Mais on n’écrit qu’au moment où le déclencheur se présente. La leçon 5 en donne un : il se trompe deux fois sur la même convention. La documentation en recense trois autres, tous vécus : une relecture attrape quelque chose qu’il aurait dû savoir sur ce code ; tu retapes une correction déjà tapée la session d’avant ; un nouveau coéquipier aurait besoin du même contexte pour être utile. Hors de ces cas, on n’écrit rien : un fichier qui grossit « au cas où » se dilue, et chaque ligne ajoutée diminue l’attention portée aux autres.

Créer le fichier, ou l’ouvrir

S’il n’existe pas encore, /init l’écrit pour toi en analysant ton code — commandes de build, façon de lancer les tests, conventions qu’il repère. Ce qu’elle produit est un brouillon, pas un fichier fini : commandes et façon de lancer les tests ont bien leur place ; la section de tri, plus bas, les range à gauche. Mais l’essentiel manque, parce qu’il ne se lit nulle part dans le code. On affine ensuite « avec les instructions que Claude n’aurait pas découvertes tout seul », puis on passe l’ensemble au tableau de tri. Si un CLAUDE.md existe déjà, elle ne l’écrase pas : elle propose des améliorations.

Ensuite, tu peux dicter « ajoute ça au CLAUDE.md ». Ou ouvrir le fichier à la main :

/memory

Tu y choisis un emplacement : ton compte, le projet, y compris ceux qui n’existent pas encore. Le fichier s’ouvre dans ton éditeur, créé s’il n’existait pas. Le même écran donne l’interrupteur de la mémoire automatique et l’entrée qui ouvre son dossier.

Savoir où il est posé

Les emplacements qui te concernent sont chargés du plus large au plus proche — et ils ne s’écrasent pas, ils s’additionnent :

~/.claude/CLAUDE.md : tes préférences à toi, sur tous tes projets ;
./CLAUDE.md, ou ./.claude/CLAUDE.md : le projet, versionné, celui que ton équipe lit ;
./CLAUDE.local.md : ce qui ne regarde que toi sur ce projet — à mettre dans ton .gitignore.

« Priorité » ne désigne ici que l’ordre de lecture : tous ces fichiers sont concaténés sur le plan de travail, le plus proche étant lu en dernier. Ce n’est pas une règle d’arbitrage : il n’existe aucun moyen d’écrire « c’est celle-là qui gagne », et le seul remède à une contradiction reste d’en retirer une — d’où la consigne officielle de relire ses fichiers périodiquement.

L’endroit d’où tu lances décide de ce qui se charge. Côté projet, lancer depuis la racine du dépôt n’apporte au démarrage que le fichier de la racine ; lancer depuis un sous-dossier apporte celui de ce dossier et ceux de tous ses parents. Les fichiers des dossiers situés en dessous, eux, attendent une condition précise — c’est le piège de la fin de cette leçon.

Trier ce qui entre, et comment on l’écrit

Le tableau officiel du tri tient en sept lignes ; en voici le nerf :

Ce qui a sa place	Ce qui n’en a pas
les commandes qu’il ne peut pas deviner, la façon de lancer les tests	tout ce qu’il peut déduire en lisant le code
les règles de style qui s’écartent des défauts	les conventions standard du langage, qu’il connaît déjà
les décisions d’architecture propres au projet, les bizarreries de l’environnement de développement	les informations qui changent souvent, la documentation détaillée d’une API — mets un lien
les pièges et les comportements non évidents	les longues explications, les tutoriels, la description fichier par fichier

Relis la colonne de droite en pensant à la divergence : ce n’est pas une liste de préférences éditoriales. Arborescence de dossiers, liste de dépendances, résumé d’architecture : tout ce que tu recopies d’une source qui bouge est une deuxième version d’une vérité qui existe déjà ailleurs. Elle deviendra fausse avant que tu ne penses à la corriger, et rien ne te le dira.

Reste la forme, et elle tient à une question : peut-on vérifier si la ligne a été respectée ? Format code properly ne se vérifie pas ; Use 2-space indentation se vérifie. La langue dans laquelle tu écris n’a aucune importance ; la forme si — court, sectionné, une instruction par puce. Une ligne qui ne décrit pas un comportement observable est vague au sens du premier des quatre facteurs : comprise de plusieurs façons, dont aucune n’est forcément la tienne.

Le test de concision, à passer ligne par ligne : est-ce que retirer cette ligne le ferait se tromper ? Si non, elle sort. Un fichier boursouflé ne se contente pas d’occuper de la place : il fait ignorer les instructions qui comptent.

Sortir ce qui n’a pas à être là en permanence

Deux cas ont une destination documentée, et l’appariement n’est pas laissé à ton intuition :

une entrée qui décrit une procédure en plusieurs étapes part dans un skill (une fiche réutilisable : du savoir ou une procédure). Un skill ne charge que sa description au démarrage, et son contenu seulement quand il sert — comment on en fabrique un : leçon 9 ;
une entrée qui ne concerne qu’une partie du code part dans un CLAUDE.md posé dans le dossier concerné, ou dans une règle limitée à des chemins.

Une règle vit dans .claude/rules/, un fichier markdown par sujet. Attention au faux mouvement : c’est le champ paths: (un bloc en tête de fichier qui liste des motifs de chemins) qui rend une règle conditionnelle, pas le dossier. Sans paths:, elle est chargée au lancement, avec la même priorité que le CLAUDE.md du projet — c’est-à-dire, au sens posé plus haut, aucun rang entre les deux. Avec, elle n’entre en scène que lorsque Claude lit un fichier correspondant.

Entre les deux, le critère documenté tient en une phrase : le CLAUDE.md de dossier quand son propriétaire veut maintenir ses conventions à côté de son code ; la règle à paths: quand tu veux toutes tes conventions au même endroit, ou la même règle pour des chemins dispersés. Il existe aussi des rules personnelles, dans ~/.claude/rules/, valables sur tous tes projets. Et si ton dépôt est un monorepo, une page entière traite le cas — les fichiers des dossiers ancêtres et des autres équipes entrent eux aussi sur ton plan de travail, claudeMdExcludes permet d’en écarter.

Vérifier qu’il est chargé, puis qu’il dit encore vrai

Le premier geste est celui de la leçon 3 : /context liste les fichiers de mémoire réellement présents sur le plan de travail, sous Memory files. Si le tien n’y est pas, il n’existe pas pour lui, et tout le reste du raisonnement est inutile.

Chargée ne veut pas dire suivie, et suivie ne veut pas dire juste. Deux signaux te disent que quelque chose cloche :

il continue de faire la chose malgré la règle → le fichier est probablement trop long, et la règle s’y perd ;
il te pose une question dont la réponse est dans le fichier → la formulation est ambiguë.

L’entretien, lui, est celui d’un bout de code, et la documentation le dit dans ces termes : on le relit quand ça va mal, on l’élague régulièrement, on teste une modification en observant si le comportement bouge réellement, on le relit en pull request (la demande de fusion qu’on ouvre pour faire vérifier un changement) comme n’importe quel changement de documentation, et on repasse dessus après une sortie de modèle.

Pour l’élagage, il existe un outil :

/doctor

Il propose trois choses, et le verbe compte : il rapporte d’abord et ne change rien sans que tu confirmes. Dédupliquer tes fichiers locaux contre celui qui est versionné ; élaguer ce dernier — couper ce que Claude peut déduire du code, garder les pièges, le raisonnement et les conventions qui s’écartent des défauts ; déplacer vers des skills ou des fichiers imbriqués ce qui n’a pas besoin d’être chargé à chaque session. Deux réserves :

la coupe vise le fichier versionné, celui que ton équipe lit. Une fois que tu as confirmé, elle se relit en pull request comme n’importe quelle autre modification — le risque serait de la valider sans la lire ;
le contrôle d’élagage demande une version au moins égale à 2.1.206 (claude --version donne la tienne). En dessous, /doctor fonctionne sans cette partie et tu tries à la main ; mettre à jour dépend de ta voie d’installation, et toutes ne se mettent pas à jour seules — leçon 2.

Ouvrir ce que l’autre mémoire a enregistré

Deux signaux la rendent visible pendant que tu travailles : les messages « Saved 2 memories » et « Recalled 2 memories » qui passent dans l’interface — un fichier vient alors d’être écrit ou lu dans son dossier.

Pour lire ce qu’elle contient : /memory, puis le dossier de mémoire automatique. Tout est du markdown ordinaire, que tu peux lire, modifier ou supprimer — ce n’est ni chiffré ni opaque. Elle est active par défaut et elle se coupe : l’interrupteur de /memory la désactive pour ton compte ; pour un seul projet, il faut poser autoMemoryEnabled à false dans les réglages de ce projet ; sinon, la variable d’environnement CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Reste le point qui décide où atterrit ce que tu dictes : quand tu lui dis « retiens que dans ce projet on n’utilise jamais telle bibliothèque », ça part dans cette mémoire-là, pas dans le CLAUDE.md. Pour le fichier versionné, il faut le demander explicitement, « ajoute ça au CLAUDE.md », ou l’écrire toi-même. Sans quoi ce qui grossit est un dossier local que ton coéquipier ne verra jamais.

Ce que ça ne fait pas

Ça ne garantit pas l’obéissance. Les leçons 3 et 4 l’ont établi et ça vaut ici : un fichier de règles est du contexte, pas une configuration appliquée, et il n’y a « aucune garantie de conformité stricte, surtout pour les instructions vagues ou conflictuelles ». Ce qui s’applique quoi que le modèle décide, ce sont les autorisations, les réglages imposés par une organisation, le bac à sable (l’isolation du système d’exploitation posée en leçon 2, qui borne les commandes shell et non ce que Claude lit ou écrit avec ses outils de fichiers ; sujet de la leçon 8) et les hooks.

Ça ne rend pas une consigne conditionnelle par magie. Ranger une instruction dans .claude/rules/ ne l’allège pas : sans paths:, elle est chargée au lancement comme le reste. Et un CLAUDE.md peut en importer d’autres avec @chemin, mais les fichiers importés sont chargés au lancement eux aussi. Ça organise, ça n’allège pas.

Piège — un fichier de règles rangé dans un sous-dossier ne s’applique pas parce que Claude « travaille dans ce dossier ». Il se charge quand Claude lit un fichier de ce dossier avec son outil de lecture : pas au lancement, et pas quand il y écrit ou y crée un fichier. Une session qui ne fait qu’écrire dans api/ ne verra jamais la règle posée dans api/CLAUDE.md. Une règle à paths: obéit à la même condition. Elle se déclenche à la lecture d’un fichier correspondant, pas à chaque action.

Ça ne survit pas toujours au ménage. Quand le plan de travail déborde, une compaction se déclenche : la conversation est résumée pour faire de la place. C’est la leçon 3, et elle en donne le tableau complet. Ce qu’il faut retenir ici : le contenu de démarrage est réinjecté depuis le disque — le CLAUDE.md à la racine du projet, celui de ton compte, les règles sans paths: et la mémoire automatique. Ce qui ne revient pas : les CLAUDE.md de sous-dossiers et les règles à chemin, perdus jusqu’à ce qu’un fichier correspondant soit relu.

La documentation en tire une conséquence, et il faut la lire en entier : pour qu’une règle survive à une compaction, on lui retire son paths: ou on la remonte à la racine. C’est un arbitrage, pas un conseil général — la racine achète la persistance et se paie en place et en dilution, exactement ce que /doctor te propose d’élaguer. Remonte ce qui doit s’appliquer sans condition, laisse en bas ce qui ne concerne qu’une partie du code.

La mémoire automatique ne suit pas ton projet. Par défaut elle est rangée sous ~/.claude/projects/<projet>/memory/, et le réglage autoMemoryDirectory déplace ce dossier ailleurs. Ce qui ne change pas, c’est qu’elle est locale à la machine : tous les worktrees d’un même dépôt la partagent, mais elle ne traverse ni une autre machine ni un environnement dans le cloud, et elle n’est pas dans ton dépôt — ton équipe ne la verra pas. C’est l’inverse exact du CLAUDE.md versionné.

Et quand son index déborde, ça peut ne pas se voir. Si une écriture pousse MEMORY.md au-delà de sa limite, elle réussit quand même — mais tout ce qui dépasse est perdu au chargement suivant. Depuis la version 2.1.210, un message d’erreur est produit ; il est adressé à Claude, pas affiché en bannière dans ton terminal, donc tu le verras dans le fil ou pas du tout. Avant, la coupe se faisait sans aucun signal. Pour regarder toi-même : /memory, le dossier de mémoire, et tu comptes les lignes de MEMORY.md.

Tous les ouvriers ne lisent pas le mot punaisé. Deux subagents intégrés, Explore et Plan, sautent toute la hiérarchie : les CLAUDE.md, celui de ton compte, le CLAUDE.local.md et les rules du projet compris. Aucun réglage ne permet de changer ça. Ce n’est pas toi qui les déclenches : Claude délègue à Explore pour chercher ou comprendre du code sans le modifier, et à Plan quand tu es en mode plan — le mode où il enquête et propose un plan sans rien modifier, sujet de la leçon 8. Tu le vois passer dans le fil. Trois réserves qui désamorcent le problème :

la conversation principale, elle, lit leurs résultats avec tout le CLAUDE.md, donc la plupart des règles n’ont pas besoin d’arriver jusqu’au subagent ;
celle qui doit y arriver se redit dans le message de délégation : « ignore le dossier vendor/ » se retape à la main quand tu demandes l’exploration ;
ta mémoire automatique n’arrive dans aucun subagent — sauf dans un fork, qui hérite de la conversation parente.

Et ce n’est pas un gain de temps. Tu ne tapes pas moins : tu déplaces une consigne de ta tête vers un endroit qui se relit, se corrige et se vérifie. C’est exactement ce que tu ne peux plus faire avec ce que tu retiens tout seul, dès lors que le projet a dépassé ce que tu tiens dans ta tête.

Où c’est écrit

Mémoire — les emplacements, l’en-tête paths: complet d’une règle, les imports et l’approbation demandée pour un import externe, la mémoire automatique et ses limites ;
Écrire un CLAUDE.md efficace — le tableau inclure/exclure entier, un exemple de fichier complet, le test de concision ;
Monorepos et grands dépôts — le critère entre CLAUDE.md par dossier et règle à chemin, l’entretien du fichier, claudeMdExcludes ;
Ce qui survit à une compaction — le tableau complet ;
Ce qui arrive dans un subagent — Explore, Plan, et ce qui ne les atteint pas ;
L’index de mémoire au-delà de sa limite — le message exact et ce qui est mesuré ;
Déboguer sa configuration — quoi faire quand une instruction n’est pas suivie.

Comme en leçons 3 et 4, ces liens pointent vers les pages anglaises ; la version française existe : /fr/ à la place de /en/. Mais elle traduit une partie des mots que tu verras sur ton écran, et elle peut être en retard sur le fond. Un lien qui vise une section précise peut d’ailleurs ne mener nulle part côté français : la section n’y est parfois pas encore traduite, et tu atterris en haut de la page sans que rien te le dise.

Le point de bascule

Tu as basculé le jour où, en te surprenant à retaper une consigne, ta première question n’est plus « comment je la formule cette fois » mais « à quel endroit elle devrait vivre — et est-ce que ce qui est écrit là-bas dit encore la vérité ? ». La deuxième moitié de la question est celle qui compte : elle a des gestes, ils sont dans cette leçon, et une règle qu’on n’entretient pas rejoint le tas de choses qu’on croit protégées.

Vérifier que c’est passé

Tu as posé un CLAUDE.md dans le dossier `api/` avec la convention de nommage de tes routes. Tu lances une session, tu lui demandes trois nouvelles routes : il les crée dans `api/` et ignore la convention. Bug ?

Non, comportement documenté : un CLAUDE.md de sous-dossier se charge quand Claude lit un fichier de ce dossier, pas quand il y écrit ou y crée un fichier. Une session qui ne fait qu’écrire ne le verra jamais.

La suite est un arbitrage, pas une réponse unique. Si la convention doit s’appliquer sans condition, elle remonte à la racine, d’où elle revient en plus toute seule après une compaction — mais elle y occupera de la place à chaque session, y compris quand tu travailles ailleurs. Si elle ne concerne vraiment que api/, garde-la en bas et accepte qu’il faille une lecture pour la réveiller : tu ne peux pas avoir les deux.

Tu lui dis « retiens qu'on n'utilise jamais cette bibliothèque ici ». La semaine suivante, ton coéquipier ouvre une session sur le même dépôt et Claude l'utilise. Que s'est-il passé ?

Ta phrase est partie dans la mémoire automatique, pas dans le CLAUDE.md. Cette mémoire est locale à ta machine, ni versionnée ni partagée entre machines. Pour vérifier ce qu’elle a retenu : /memory, puis le dossier de mémoire automatique, où tout est du markdown lisible et modifiable. Et pour que la règle existe pour l’équipe, il faut le demander explicitement — « ajoute ça au CLAUDE.md » — ou ouvrir le fichier et l’écrire.

Ton CLAUDE.md fait 400 lignes. On te dit qu'au-delà de 200, la suite n'est pas lue, et on te conseille de couper en deux fichiers importés. Est-ce que tes 400 lignes sont lues ?

Oui, en entier, et c’est la première des deux erreurs à démonter. Un CLAUDE.md est chargé en entier quelle que soit sa longueur : les 200 lignes sont une cible, et ce qui baisse au-delà c’est l’adhérence, pas la lecture — le vrai couperet à 200 lignes ne concerne que l’index de la mémoire automatique. Le conseil, ensuite : découper en imports @chemin n’allège rien : les fichiers importés sont chargés au lancement eux aussi. Ce qui réduit la charge permanente, c’est de sortir les procédures vers des skills et de limiter des rules à des chemins — ou d’élaguer, ce que /doctor propose.

Et le symptôme t’a déjà renseigné : un fichier trop long est la première explication documentée quand Claude continue de faire une chose malgré une règle qui l’interdit.