Le fichier CLAUDE.md

Chaque session Claude Code démarre avec une fenêtre de contexte vierge. Le fichier CLAUDE.md est le moyen de lui transmettre, à chaque fois, ce qu'il ne peut pas deviner : vos commandes de build, vos conventions, vos pièges connus. Cette leçon présente où le placer, comment il se charge et comment l'organiser quand le projet grandit. Tous les points ont été vérifiés sur la documentation officielle de Claude Code (page « memory ») le 23 septembre 2026.

Une mémoire que vous écrivez

Claude Code dispose de deux mécanismes de mémoire complémentaires : les fichiers CLAUDE.md, que vous rédigez, et une mémoire automatique, où Claude note lui-même des apprentissages au fil des sessions. Les deux sont chargés au démarrage d'une conversation.

Point essentiel : Claude traite CLAUDE.md comme du contexte, pas comme une règle appliquée mécaniquement. Plus vos consignes sont précises et courtes, mieux elles sont suivies. Pour une interdiction qui doit tenir quoi qu'il arrive, un hook est l'outil adapté (voir la leçon Les hooks).

Les portées : du plus large au plus précis

Un CLAUDE.md peut vivre à plusieurs endroits, chacun avec sa portée :

Ces fichiers ne s'écrasent pas : ils sont concaténés. Claude Code lit ceux du répertoire de travail et de chaque dossier parent au lancement, du plus haut au plus proche, si bien que les instructions les plus spécifiques sont lues en dernier.

Les CLAUDE.md placés dans des sous-dossiers fonctionnent différemment : ils ne sont pas chargés au démarrage, mais à la demande, quand Claude lit des fichiers de ce sous-dossier. Pratique dans un monorepo : les consignes du backend/ n'encombrent pas une session qui ne touche qu'au frontend/.

Importer d'autres fichiers avec @

Un CLAUDE.md peut en inclure d'autres avec la syntaxe @chemin. Les chemins relatifs se résolvent par rapport au fichier qui importe, et les imports peuvent s'enchaîner jusqu'à quatre niveaux.

# Projet boutique
 
Vue d'ensemble : @README.md
Scripts disponibles : @package.json
 
## Conventions Git
 
@docs/git-workflow.md

Attention : un fichier importé est chargé au lancement, comme le reste. Les imports aident à organiser, pas à économiser du contexte. Un chemin écrit entre accents graves reste du texte et n'est pas importé.

Et AGENTS.md ?

AGENTS.md est le fichier de consignes lu par d'autres agents de code, dont Codex. Depuis la version 2.1.277 (vérifié le 26/09/2026 sur la documentation officielle), Claude Code le lit aussi : si le dépôt n'a aucun CLAUDE.md (ni CLAUDE.local.md) dans le dossier de travail ou au-dessus, il charge AGENTS.md à la place. S'il trouve un CLAUDE.md, il ignore AGENTS.md, sauf si vous l'importez avec la ligne @AGENTS.md ou si le réglage « Project instructions » de /config demande de lire les deux. Une équipe qui mélange les outils peut ainsi garder une seule source de vérité (voir Codex vs Claude Code).

Découper avec .claude/rules/

Quand les consignes s'allongent, le dossier .claude/rules/ permet de les répartir en fichiers thématiques (tests.md, api.md…), découverts récursivement. Un fichier de règles sans en-tête s'applique toujours. Avec un frontmatter paths, il ne se charge que lorsque Claude lit des fichiers correspondant aux motifs :

---
paths:
  - "src/api/**/*.ts"
---
 
- Chaque route valide ses entrées avant tout traitement.
- Les erreurs suivent le format de réponse commun du projet.

Des règles personnelles valables pour tous vos projets peuvent aussi être placées dans ~/.claude/rules/.

Consulter et modifier : /memory

La commande /memory liste vos fichiers CLAUDE.md et CLAUDE.local.md, ainsi que la mémoire automatique, et ouvre celui que vous choisissez dans votre éditeur. Pour vérifier ce qui est réellement chargé dans la session en cours, utilisez /context. Bon à savoir : après un /compact, le CLAUDE.md racine est relu depuis le disque et réinjecté.

Rédiger un CLAUDE.md utile

• Visez court : la documentation conseille de rester sous environ 200 lignes par fichier. Au-delà, déplacez le détail dans des règles ciblées.
• Soyez vérifiable : « indentation de 2 espaces » vaut mieux que « code propre ».
• Évitez les contradictions : deux consignes opposées, et Claude peut en choisir une arbitrairement. Relisez régulièrement l'ensemble.
• Versionnez le CLAUDE.md de projet pour que toute l'équipe en profite.

Pour la certification

La hiérarchie CLAUDE.md (utilisateur, projet, sous-dossier), les imports, .claude/rules/ et /memory figurent explicitement dans le domaine « configuration et workflows de Claude Code » : voir le détail des domaines de l'examen. Un piège classique : une consigne placée dans ~/.claude/CLAUDE.md n'est pas partagée avec l'équipe. La leçon suivante, Contexte et fenêtre de contexte, explique pourquoi chaque ligne chargée compte.