Un CLAUDE.md qui sert vraiment
Ce qu'on y met, ce qu'on n'y met pas, et pourquoi un fichier trop long est pire qu'un fichier absent.
Le CLAUDE.md est le fichier que Claude Code lit au démarrage de chaque session. C'est aussi celui que tout le monde remplit trop, jusqu'à ce qu'il devienne du bruit que le modèle survole. Un fichier de quinze lignes bien choisies bat un fichier de deux cents lignes.
Ce guide propose une méthode pour arriver aux quinze lignes.
Le principe
Ce fichier coûte des tokens à chaque session, sur chaque tâche. Une ligne n'y a sa place que si elle remplit les trois conditions :
- Non déductible. Le modèle ne peut pas la trouver en lisant le code.
- Durable. Elle sera encore vraie dans trois mois.
- Conséquente. Sans elle, Claude ferait quelque chose de faux.
Une ligne qui rate une seule de ces trois conditions rend le fichier plus long sans le rendre plus utile.
Le test de la suppression
Pour chaque ligne : que se passerait-il si je l'enlevais ? Si tu ne vois pas de différence concrète, la ligne est décorative.
Avant de commencer
- Un projet avec un CLAUDE.md, même mauvais
- Claude Code installé
- Vingt minutes
1Partir d'une base générée
/init
Claude lit le dépôt et écrit un premier jet. Cette base est volontairement généreuse : elle sert de matière à couper, pas de version finale.
2Couper les quatre familles inutiles
Passe le fichier et supprime :
- L'inventaire. Arborescence, liste des dépendances, description de la stack. Le modèle ouvre le dépôt.
- Les évidences. « Écris du code lisible », « ajoute des tests ». Il le fait déjà, et l'écrire n'y change rien.
- L'historique. Les décisions passées vivent dans
git loget dans les ADR. - Le ponctuel. « On migre vers la v2 cette semaine » sera faux dans dix jours et personne ne l'enlèvera.
3Garder les cinq familles utiles
Ce qui reste tourne presque toujours autour de cinq choses :
# Projet
## Commandes
- Tests : `make test` (pas `npm test`, qui saute les tests d'integration)
- Migrations : `make db-migrate`
## Interdits
- Ne pas modifier `legacy/`, ce dossier est supprime en janvier
- Ne jamais commiter sur `main`, toujours une branche
## Conventions non evidentes
- Les dates sont stockees en UTC, converties a l'affichage seulement
- Les messages de commit sont en francais, a l'imperatif
## Pieges connus
- Le seed de la base echoue si Docker n'est pas lance avant
Commandes, interdits, conventions arbitraires, pièges. Quatre rubriques suffisent dans la plupart des dépôts.
4Écrire à l'impératif
Les formulations molles se font ignorer. La différence est mesurable dans le comportement :
| À éviter | À écrire |
|---|---|
Il serait preferable d'utiliser pnpm | Utilise pnpm. Jamais npm. |
Essaie de ne pas toucher au dossier legacy | Ne modifie aucun fichier de legacy/. |
Les tests sont importants | Lance make test avant de dire qu'une tache est finie. |
Une consigne est une règle ou elle n'a rien à faire là.
5Alimenter au fil de l'eau
Le fichier ne doit pas être écrit d'un bloc puis oublié. Chaque fois que tu
corriges Claude sur un point qui reviendra, ajoute la ligne avec le raccourci
# :
# Les composants vont dans src/components, jamais dans src/ui.
Claude te propose le fichier de destination et ajoute la ligne. C'est le seul mécanisme qui maintient un CLAUDE.md vivant sans y consacrer de temps.
Un fichier par sous-projet
Dans un monorepo, un CLAUDE.md à la racine pour les règles communes, et un par paquet pour les spécificités. Ils se cumulent, chacun reste court.
Un exemple complet
# atelier-api
## Commandes
- Dev : `make dev` (lance Postgres + l'API)
- Tests : `make test`, jamais `pytest` seul
- Lint : `make lint`, obligatoire avant commit
## Interdits
- Ne pas editer les fichiers de `alembic/versions/` deja appliques
- Ne pas ajouter de dependance sans en parler dans la PR
## Conventions
- Les routes sont en anglais, les messages d'erreur en francais
- Toute date en base est en UTC
## Pieges
- `make dev` echoue silencieusement si le port 5432 est deja pris
Dix-huit lignes. Chacune change ce que Claude fait.
Le signe que ça marche
Tu arrêtes de reprendre Claude sur les mêmes points. Si tu te surprends à répéter une consigne pour la troisième fois, elle manque dans le fichier. Si le fichier grossit mais que tu répètes toujours autant, c'est qu'il contient les mauvaises lignes.
Tu as d’autres ressources comme ça ?
Ce que tu viens de lire est entièrement gratuit. Une nouvelle ressource part chaque semaine dans la newsletter : guides, modèles à copier et liens triés, sans compte à créer.
Me contacter
Une question, un projet, une envie de collaborer ? Écris-moi.
Cette page est en accès libre, n’hésite pas à la partager.