Claude Code écrit du code correct dès la première session. Le problème, c'est qu'il écrit du code correct à sa façon : un autre style de nommage, une autre librairie de dates que celle du projet, des tests rangés au mauvais endroit. Le fichier CLAUDE.md règle ce problème. C'est la pièce la plus rentable de tout le dispositif, et la plus souvent bâclée.
Ce guide explique ce qu'est le fichier CLAUDE.md, ce qu'il doit contenir, ce qu'il ne doit pas contenir, et comment le faire vivre. Il vient de nos propres projets : chaque dépôt qu'on livre à un client en a un, et le site sur lequel vous lisez cet article aussi.
CLAUDE.md : ce que c'est et comment Claude Code le lit
CLAUDE.md est un fichier texte, au format Markdown, placé à la racine d'un dépôt. Claude Code le lit automatiquement au début de chaque session et le garde en contexte pendant tout le travail. C'est la mémoire du projet : ce qu'un nouveau développeur devrait savoir avant de toucher au code, écrit pour un agent.
Trois propriétés en font un outil puissant :
- il est relu à chaque session. Une consigne donnée dans une conversation est perdue à la conversation suivante. Une consigne écrite dans le fichier tient pour toujours ;
- il est versionné avec le code. On le corrige par un commit, on voit qui l'a changé et pourquoi, et toute l'équipe a la même version ;
- il est hiérarchique. On peut en placer un à la racine, d'autres dans des sous-dossiers pour les règles propres à une partie du code, et un fichier personnel dans son dossier utilisateur pour ses préférences.
Les emplacements possibles
- À la racine du dépôt : les règles du projet, partagées par toute l'équipe. C'est le fichier principal.
- Dans un sous-dossier : des règles qui ne valent que là, par exemple pour le dossier des migrations ou pour une application dans un monorepo. Claude Code les charge quand il travaille dans ce dossier.
- Dans
~/.claude/CLAUDE.md: vos préférences personnelles, valables sur tous vos projets. Votre langue, votre façon de rédiger les messages de commit.
Les imports
Un CLAUDE.md peut en inclure un autre avec la syntaxe @chemin/du/fichier. C'est utile pour ne pas dupliquer : beaucoup de projets ont déjà un fichier AGENTS.md, le format lu par d'autres agents de code comme Codex. Le CLAUDE.md de ce site tient en une ligne : @AGENTS.md. Les deux outils lisent ainsi les mêmes règles, et on n'a qu'un fichier à maintenir. Nous comparons ces agents dans notre article OpenAI Codex vs Claude Code.
Ce qu'il faut mettre dans un CLAUDE.md
Les commandes
C'est le contenu le plus utile et le plus souvent oublié. Comment on installe, comment on lance l'application en local, comment on lance les tests, comment on vérifie les types, comment on lint. Sans ça, l'agent devine, et il devine souvent mal : npm test au lieu de pnpm test:unit, un serveur lancé sur le mauvais port.
## Commandes
- Installer : `pnpm install`
- Lancer en local : `pnpm dev` (port 3000)
- Tests : `pnpm test` ; un seul fichier : `pnpm test chemin/du/test`
- Types : `pnpm typecheck` avant chaque commit
L'architecture, en quelques lignes
Pas un document d'architecture complet. Juste ce qui évite à l'agent d'explorer quarante fichiers pour comprendre où va quoi : où sont les routes, où est la logique métier, où sont les accès à la base de données, quel dossier ne jamais modifier à la main parce qu'il est généré.
Les conventions qui ne se devinent pas
Tout ce qu'un développeur expérimenté ferait différemment de votre équipe. La librairie de dates utilisée. La façon de gérer les erreurs. Le nommage des fichiers. La langue des commentaires et des messages de commit. Si vos commentaires sont en français, écrivez-le : sinon l'agent les écrira en anglais.
Les pièges connus
C'est la section qui rapporte le plus avec le temps. Chaque fois que l'agent fait une erreur qu'il ne devrait pas refaire, on l'ajoute ici. « Le fichier de migration doit être rejouable, ne jamais modifier une migration déjà appliquée. » « Cette version du framework a changé l'API du routage : lire la documentation locale avant d'écrire. » Le fichier devient une liste des leçons apprises par le projet.
Ce qui est interdit
Les zones à ne pas toucher, les commandes à ne jamais lancer, les données à ne jamais afficher. Mais attention : une interdiction écrite dans CLAUDE.md est une consigne, pas un verrou. Pour ce qui est vraiment critique, il faut un garde-fou mécanique (les permissions de Claude Code ou un hook qui bloque l'action). Nous détaillons ces garde-fous dans notre retour d'expérience sur Claude Code en production.
Ce qu'il ne faut pas y mettre
La documentation complète. Le fichier est chargé à chaque session et occupe de la place dans la fenêtre de contexte. Un CLAUDE.md de mille lignes coûte des tokens à chaque requête et noie les consignes importantes. Visez quelques centaines de lignes au maximum, et renvoyez vers d'autres fichiers pour le détail : l'agent les lira quand il en aura besoin.
Les évidences. « Écris du code propre », « fais attention aux bugs ». L'agent le fait déjà, et ces phrases diluent les vraies règles.
Les secrets. Le fichier est versionné et lu par un service externe. Aucune clé d'API, aucun mot de passe, aucune URL interne sensible.
Les consignes contradictoires. Un fichier qui a grossi par ajouts successifs finit par se contredire. Relisez-le en entier de temps en temps et supprimez ce qui ne vaut plus.
Un modèle de CLAUDE.md pour démarrer
Portail client : application Next.js + Supabase. Le front est dans `app/`, la logique
métier dans `lib/`, les accès base dans `lib/db/`. `lib/db/types.ts`
est généré : ne jamais le modifier à la main.
## Commandes
- `pnpm dev` pour lancer, `pnpm test` pour les tests,
`pnpm typecheck` avant chaque commit.
## Conventions
- Commentaires et messages de commit en français.
- Dates : uniquement `date-fns`, jamais `moment`.
- Toute nouvelle table a une policy RLS dans la même migration.
## Pièges
- Ne jamais modifier une migration déjà appliquée : en créer une nouvelle.
- Les montants sont stockés en centimes (entiers), jamais en décimal.
## Interdit
- Pas de `git push` : la revue humaine se fait sur la pull request.
Ce modèle tient en vingt lignes. Il suffit à éviter la majorité des erreurs d'un agent sur un projet de ce type.
Comment le faire vivre
Le générer, puis le réécrire
La commande /init de Claude Code analyse le dépôt et produit un premier CLAUDE.md. C'est un bon point de départ pour les commandes et l'architecture. Mais ce premier jet décrit ce que le code contient, pas ce que l'équipe sait. Les conventions implicites et les pièges, c'est à vous de les ajouter.
Le corriger à chaque dérive
La règle la plus utile : chaque fois que vous corrigez l'agent deux fois sur le même point, la correction va dans le fichier. Une semaine de ce régime suffit à rendre le fichier vraiment utile. Un mois, et l'agent code comme quelqu'un qui connaît le projet depuis longtemps.
Le relire en revue de code
Le fichier fait partie du code. Ses modifications passent par la même revue que le reste. C'est aussi ce qui garantit que les règles restent celles de l'équipe, et pas celles d'un seul développeur.
Le fichier qui fait la différence
On voit souvent des équipes conclure que Claude Code « ne comprend pas leur projet ». Dans la plupart des cas, le projet n'a pas de CLAUDE.md, ou un fichier généré jamais relu. L'agent n'a aucun moyen de deviner ce que l'équipe sait sans l'avoir écrit.
C'est par ce fichier qu'on commence chaque mission de développement avec Claude Code : avant la première ligne de code, on écrit avec l'équipe ce qui doit être su. C'est ce qui permet d'entrer dans un dépôt existant, même ancien, et d'y livrer du code qui ressemble au reste.
