Chapitre 2 · Chapitre 2 · Découvrir CLAUDE.md
2.1 À quoi sert ce fichier, et comment est-il chargé ?
Suis cette formation dans ton espace : ta progression est gardée, et la communauté répond à tes questions.
Suivre gratuitementCLAUDE.md est un simple fichier texte au format Markdown (un format où # fait un titre et - une liste). Il contient des instructions persistantes : des consignes qui restent valables d'une session à l'autre. Pas de logiciel spécial, pas de syntaxe compliquée : tu l'écris comme une note bien rangée.
Comment Claude Code le charge
- Au démarrage, Claude Code cherche les fichiers
CLAUDE.md(etCLAUDE.local.md) dans ton dossier de travail et dans tous les dossiers au-dessus. Par exemple, lancé dansclients/boulangerie/, il litclients/boulangerie/CLAUDE.mdet aussiclients/CLAUDE.mds'il existe. - Tous les fichiers trouvés sont additionnés : aucun n'efface les autres. Ils sont placés du plus général au plus précis, donc les instructions les plus proches de ton dossier de lancement sont lues en dernier. Dans un même dossier,
CLAUDE.local.mdpasse aprèsCLAUDE.md. - Les fichiers CLAUDE.md placés dans des sous-dossiers ne sont pas lus au démarrage : ils sont chargés quand Claude lit, écrit ou modifie un fichier de ce sous-dossier.
- Son contenu arrive comme un message de consignes juste après les instructions internes de Claude Code (pas dans ces instructions internes elles-mêmes). Claude le lit et essaie de le suivre, mais sans garantie stricte. C'est pour ça que des règles claires et précises sont mieux suivies que des règles floues.
Un exemple avec mes-videos-ia
Imagine cette organisation :
creations/
CLAUDE.md (« Réponds en français, tutoiement. »)
mes-videos-ia/
CLAUDE.md (« Public : débutants. Vidéos de 40 à 55 secondes. »)
video-12/
CLAUDE.md (« Cette vidéo est une série en 3 parties. »)
Si tu lances Claude Code dans mes-videos-ia/, il charge au démarrage creations/CLAUDE.md puis mes-videos-ia/CLAUDE.md. Le fichier de video-12/ arrive seulement quand Claude travaille sur un fichier de ce dossier. Quand il se charge, une ligne Loaded avec son chemin apparaît dans le terminal.
Petit détail pratique : les commentaires
Les commentaires HTML écrits sur leur propre bloc sont retirés avant d'être donnés à Claude. Tu peux t'en servir pour laisser des notes pour toi ou ton équipe, sans encombrer son contexte :
<!-- Note pour moi : revoir la règle sur la musique en décembre -->
## Vidéos
- Durée : 40 à 55 secondes.
Claude reçoit la section « Vidéos », pas la note. Attention : un commentaire placé à l'intérieur d'un bloc de code est conservé.
Quand une modification est-elle prise en compte ?
Le plus simple et le plus sûr : après avoir modifié ton CLAUDE.md, ouvre une nouvelle session (ou tape /clear) et vérifie avec /context qu'il apparaît bien dans Memory files. Si la liste est repliée, /context all l'affiche en entier.
Bon à savoir : après un /compact, le CLAUDE.md à la racine du projet est relu depuis le disque. Mais pour tester proprement une nouvelle règle, rien ne vaut une session neuve, où tu es sûr que Claude ne s'appuie pas sur la conversation précédente.
Et si mon projet a un AGENTS.md ?
Certains projets ont déjà un fichier AGENTS.md, utilisé par d'autres assistants de code. La documentation indique que Claude Code peut le lire à la place de CLAUDE.md quand aucun CLAUDE.md n'existe dans le dossier ou au-dessus. Si tu débutes, tu n'en as pas besoin : retiens simplement que CLAUDE.md reste le fichier principal. Pour les détails (versions, réglage dans /config), vérifie la page « memory » de la documentation officielle.
Si ça coince
- Ton fichier de sous-dossier n'apparaît pas dans Memory files : c'est normal, il se charge à la demande. Demande à Claude de lire un fichier de ce sous-dossier, puis cherche la ligne
Loadeddans le terminal. - Le fichier n'est pas lu du tout : vérifie le nom exact (
CLAUDE.md, en majuscules, extension.md) et le dossier de lancement. - Une ancienne version de la règle est appliquée : tu as modifié le fichier pendant la session. Ouvre une nouvelle session pour repartir propre.
À retenir
- CLAUDE.md est un fichier Markdown d'instructions persistantes.
- Claude Code lit les CLAUDE.md du dossier de lancement et des dossiers au-dessus, et les additionne.
- Ceux des sous-dossiers se chargent quand Claude travaille dans ces sous-dossiers.
- Après une modification, teste dans une nouvelle session et vérifie avec
/context.