Le fichier CLAUDE.md

Chaque session de Claude Code démarre avec une fenêtre de contexte vierge. Pour que Claude n’ait pas à redécouvrir chaque matin la commande qui lance vos tests ou la décision prise par l’équipe la semaine dernière, il existe le fichier CLAUDE.md : un fichier Markdown d’instructions que Claude lit au début de chaque session. C’est la première personnalisation à mettre en place, et la plus rentable.

Ce qu’est CLAUDE.md, et ce qu’il n’est pas

Vous écrivez CLAUDE.md en texte libre ; Claude le lit à chaque session. La documentation insiste sur un point : Claude traite ces fichiers comme du contexte, pas comme une configuration imposée. Il suit très généralement leurs consignes, mais peut juger qu’une consigne ne s’applique pas. Pour une règle qui ne souffre aucune exception, comme « ne jamais lire .env », il faut un mécanisme que Claude Code applique lui-même : un hook ou une règle de refus (leçon 12).

À côté de CLAUDE.md, que vous écrivez, existe la mémoire automatique, que Claude tient lui-même : des notes sur vos préférences, vos corrections et l’état du travail, rangées dans ~/.claude/projects/<projet>/memory/. Quand vous dites « souviens-toi que les tests d’API demandent un Redis local », Claude l’enregistre dans cette mémoire. Pour l’inscrire plutôt dans CLAUDE.md, dites-le explicitement : « ajoute ceci à CLAUDE.md ».

Où placer le fichier

Claude Code charge les fichiers du dossier de travail et de tous les dossiers parents. Ils s’additionnent au lieu de se remplacer ; ceux des sous-dossiers se chargent à la demande, quand Claude travaille dans ces sous-dossiers. Si votre dépôt contient déjà un AGENTS.md écrit pour d’autres agents de code et pas de CLAUDE.md, Claude lit l’AGENTS.md à la place.

Démarrer avec /init

Inutile de partir d’une page blanche : /init analyse votre base de code et génère un premier CLAUDE.md avec les commandes de build, les instructions de test et les conventions qu’il a trouvées. Si un fichier existe déjà, il propose des améliorations au lieu de l’écraser. Le travail consiste ensuite surtout à retirer des lignes, puis à ajouter ce que Claude ne pouvait pas deviner.

Ce qu’il faut y écrire

La règle officielle : n’écrivez que ce que Claude ne peut pas trouver en lisant le dépôt. Il découvre seul l’organisation des fichiers, les conventions et le framework de test. Ce qui mérite une ligne :

• comment vérifier le travail : les commandes exactes de test, de typage et de lint, et comment lancer un seul fichier de test ;
• les endroits où le code induit en erreur : un vieux motif présent partout que le nouveau code ne doit pas copier, un dossier qui semble mort mais ne l’est pas ;
• les décisions absentes du dépôt : la fonction d’erreur choisie par l’équipe, la façon de déployer, ce qui exige une revue de migration ;
• tout ce que vous avez déjà dû corriger deux fois.

Voici l’exemple que donnent les bonnes pratiques officielles :

# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit

# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code

# Gotchas
- Integration tests need DATABASE_URL set, see .env.example

Écrivez des consignes vérifiables : « indentation de 2 espaces » plutôt que « formate correctement le code », « lance npm test avant de commiter » plutôt que « teste tes changements ». Visez moins de 200 lignes par fichier : chaque ligne prend un peu de l’attention de Claude à chaque tâche, et un fichier trop long est moins bien suivi. Inutile d’ajouter IMPORTANT ou des majuscules : les modèles actuels suivent une consigne écrite simplement, et l’insistance les pousse plutôt à trop l’appliquer. Si une ligne est ignorée, soit le fichier est trop long, soit c’est une règle qui doit devenir un hook.

Organiser un fichier qui grandit

• Les imports : une ligne @docs/git-instructions.md intègre un autre fichier au contexte. Pratique pour organiser, mais le fichier importé est chargé avec le reste : cela ne réduit pas le coût en contexte.
• Les règles par dossier : des fichiers dans .claude/rules/, avec un champ paths: dans leur en-tête, ne se chargent que lorsque Claude travaille sur les fichiers correspondants. Une règle sur les API ne coûte rien tant que Claude ne touche pas à src/api/.
• Les skills : une procédure en plusieurs étapes ou un savoir propre à une seule partie du code a plutôt sa place dans une skill (leçon 10), qui ne se charge qu’au moment où elle sert.

Vérifier et entretenir

• /memory liste vos fichiers CLAUDE.md et de mémoire, permet d’activer ou non la mémoire automatique et ouvre le fichier choisi dans votre éditeur.
• /context montre quels fichiers CLAUDE.md ont été chargés dans la session.
• /doctor prompt-audit (version 2.1.283 ou ultérieure) repère les consignes écrites pour d’anciens modèles, celles qui citent des fichiers disparus et celles qui se contredisent ; rien n’est modifié sans votre accord.

Ajoutez une ligne quand Claude fait deux fois la même erreur, quand une revue relève quelque chose qu’il aurait dû savoir, ou quand un nouveau venu aurait besoin de la même information. Le CLAUDE.md à la racine du projet survit aux compactions : il est relu depuis le disque.

À vous de jouer

Votre premier CLAUDE.md. Lancez /init dans un projet, puis relisez le fichier produit : gardez les commandes de build et de test, les conventions vérifiables et les pièges réels, et retirez le reste. Visez moins de 200 lignes. Vérifiez ensuite avec /memory quels fichiers Claude charge.

Sources officielles : The CLAUDE.md file (Claude Academy) · How Claude remembers your project · Best practices

Points clés à retenir

• CLAUDE.md est lu à chaque session ; c’est du contexte, pas une règle imposée
• Quatre portées : organisation, utilisateur (~/.claude/CLAUDE.md), projet (./CLAUDE.md, partagé), local (CLAUDE.local.md, ignoré par git)
• /init génère une première version ; gardez-la sous 200 lignes, avec seulement ce que Claude ne peut pas trouver seul
• Les règles par dossier (.claude/rules/) et les skills évitent de tout charger tout le temps
• /memory pour éditer, /context pour vérifier ce qui est chargé