Skip to Content
Claude CodePartie 3 — CLAUDE.md, mémoire & conventions3.1 — Anatomie du CLAUDE.md

Chapitre 3.1 — Anatomie du CLAUDE.md

⏱️ TL;DR — Le CLAUDE.md est un fichier Markdown que Claude Code injecte automatiquement dans le contexte au démarrage et garde présent toute la session. Il en existe plusieurs niveaux qui se cumulent : global (ton ~/.claude/), projet (racine du repo), et par dossier (chargé quand l’agent travaille dedans). Comprendre quand chaque niveau se charge, c’est savoir où mettre quelle règle.

🎯 Objectifs

  • Savoir où vivent les fichiers de mémoire et quand chacun est chargé.
  • Comprendre le cumul (global + projet + dossier) et sa logique.
  • Distinguer CLAUDE.md (versionné, partagé) de CLAUDE.local.md (perso, ignoré par git).
  • Placer une règle au bon niveau.

Où vit la mémoire

  • Global (~/.claude/CLAUDE.md) : tes préférences transversales, quel que soit le projet (ex. « réponds en français », « préfère les fonctions pures »). Il te suit partout.
  • Projet (./CLAUDE.md à la racine) : le cœur. Conventions du repo, versionné dans git, donc partagé avec quiconque (humain ou agent) travaille dessus.
  • Dossier (src/features/billing/CLAUDE.md) : des règles locales, chargées quand l’agent touche à ce dossier. Utile quand un sous-domaine a ses propres contraintes.

Les niveaux se cumulent (ils ne s’écrasent pas) : l’agent voit le global + le projet, plus le dossier concerné le cas échéant.

💡 Réflexe d’architecte — Range chaque règle par sa portée. « J’aime les commits courts » → global (c’est toi, partout). « Ce repo utilise des server actions » → projet (c’est le repo). « Ce module ne doit jamais importer le client HTTP directement » → dossier (c’est ce coin du code). Une règle au mauvais niveau, c’est du bruit pour les autres contextes.

CLAUDE.md vs CLAUDE.local.md

  • CLAUDE.md — versionné, partagé. Ce que toute l’équipe (et tout agent) doit respecter.
  • CLAUDE.local.md — non versionné (à ignorer dans .gitignore), pour tes notes perso propres à ce repo (« ma base de test tourne sur le port 5433 »). Tes bricoles, pas celles de l’équipe.

⚠️ Piège — Mettre des chemins/secrets/particularités de ta machine dans le CLAUDE.md versionné. Ça pollue le contexte de tes collègues et de l’agent chez eux. Le personnel va dans CLAUDE.local.md (ou dans ta mémoire globale) ; le partagé va dans CLAUDE.md.

Comment il est chargé (et ce que ça implique)

Le point capital, déjà vu au chapitre 1.3 : le CLAUDE.md est chargé dès le début et reste dans le contexte. Conséquences directes :

  1. Il est toujours là → parfait pour ce qui vaut pour presque toute tâche (conventions, stack). C’est sa force.
  2. Il coûte du contexte en permanence → chaque ligne inutile est payée à chaque tâche. C’est sa contrainte. D’où l’obsession du chapitre suivant : le garder court.
  3. Le haut compte plus → l’agent pondère davantage le début du fichier. Les règles vitales vont en premier.

📚 Aller plus loin — Tu peux inspecter ce que l’agent a réellement chargé en lui demandant « quels fichiers de mémoire as-tu en contexte ? ». Utile pour vérifier qu’un CLAUDE.md de dossier est bien pris en compte, ou qu’aucun fichier obèse ne traîne.

Un fichier, pas un dépotoir

Le CLAUDE.md n’est pas : un journal de bord, une doc d’architecture exhaustive, un backlog, un endroit où coller des specs. Tout ça vit ailleurs (docs, ADR, issues). Le CLAUDE.md répond à une question : « Que doit savoir l’agent, en permanence, pour bien travailler ici ? » Rien de plus.

🧭 Sur TaskFlow — Notre graine de CLAUDE.md (2.5) est déjà au bon niveau : projet, versionnée. En 3.5, on l’étoffera sans la faire gonfler, et on ajoutera peut-être un CLAUDE.md de dossier pour src/features/ si un contrat local le justifie.

✏️ Exercices

Exercice 1 — Trie par portée. Prends 8 règles que tu donnes souvent à l’agent. Classe chacune : global / projet / dossier. Combien étaient au mauvais niveau (ex. une préférence perso dans un CLAUDE.md d’équipe) ?

✅ Solution

Cas fréquents de mauvais rangement : préférences de style perso (« pas de point-virgule ») dans le CLAUDE.md projet → devraient être en global ; particularités de ta machine dans le versionné → CLAUDE.local.md. Bien trier, c’est réduire le bruit dans chaque contexte.

Exercice 2 — Inspecte. Sur un vrai repo, demande à l’agent la liste des fichiers de mémoire qu’il a chargés. Y a-t-il un fichier que tu avais oublié ? un fichier de dossier jamais pris en compte ?

✅ Solution

Tu découvres parfois un CLAUDE.md global ancien qui influence tout, ou un CLAUDE.md de dossier au mauvais endroit (donc jamais chargé). L’inspection est le moyen simple de vérifier que ta hiérarchie fait ce que tu crois.

🧠 Quiz de révision

1. Quels sont les trois niveaux de mémoire et leur portée ?

Global (~/.claude/CLAUDE.md, tes préférences sur tous projets), projet (./CLAUDE.md, conventions du repo, versionné), dossier (src/.../CLAUDE.md, règles locales chargées quand l’agent y travaille). Ils se cumulent.

2. Différence entre CLAUDE.md et CLAUDE.local.md ?

CLAUDE.md est versionné/partagé (conventions d’équipe) ; CLAUDE.local.md est ignoré par git (tes notes perso propres au repo, ex. ports de dev). Le personnel ne pollue pas le partagé.

3. Pourquoi les règles vitales doivent-elles être en haut du fichier ?

Parce que l’agent pondère davantage le début du CLAUDE.md. Le haut = les règles non négociables ; le bas = le moins critique.

4. Pourquoi chaque ligne inutile du CLAUDE.md a-t-elle un coût ?

Parce qu’il est chargé en permanence : chaque ligne est payée (en contexte et en attention) à chaque tâche. Un fichier obèse dilue les vraies règles.

5. Le CLAUDE.md est-il l’endroit pour documenter l’architecture en détail ?

Non. Il répond à « que doit savoir l’agent en permanence pour bien travailler ici ». La doc d’archi, les specs, le backlog vivent ailleurs (docs, ADR, issues).

Chapitre suivant : Écrire un bon CLAUDE.md — les règles concrètes d’un fichier qui est vraiment suivi.

Vue d'ensemble3.2 — Écrire un bon CLAUDE.md