Un CLAUDE.md qui change les décisions, pas qui décrit le projet
La plupart sont un README renommé. Le test : un agent pourrait-il agir différemment à cause de cette ligne ?
CLAUDE.md se trouve à la racine du projet et Claude Code le lit au début de chaque session. La plupart de ceux que nous voyons sont un README renommé. Un fichier utile ressemble plutôt à un ensemble de corrections permanentes.
Écrivez les décisions, pas la description
Le test de chaque ligne : un agent pourrait-il agir différemment à cause d'elle ? Une phrase expliquant que l'entreprise fait des sites de santé ne change rien. Une phrase disant qu'aucune page ne peut porter une statistique client sans source nommée change ce qui s'écrit partout.
Ce qui y a sa place sur un projet web
| Section | Pourquoi elle mérite sa place |
|---|---|
| Pile et versions | Framework avec sa version majeure, approche de style, et ce qu'il ne doit pas installer. |
| Modèle de contenu | Où vivent les textes et quels fichiers sont des données. C'est ce qui empêche de coder un titre en dur. |
| Politique des affirmations | Ce qui peut être affirmé et ce qui exige une source. La section la plus précieuse. |
| Style maison | Ponctuation, ton, mots proscrits. Peu coûteux à énoncer, sinon recorrigé sans fin. |
| Vérification | Quelle commande prouve qu'un changement marche. Sans cela, l'agent déclare le succès sur un build propre. |
| Pièges connus | Les bugs que ce dépôt a déjà produits deux fois. La section qui grandit et qui rapporte. |
Gardez-le assez court pour être lu
Il se charge au début de chaque session, donc chaque ligne est payée à chaque tour. Un fichier de mille lignes dilue les vingt qui comptent. Élaguez-le comme une suite de tests. Claude Code construit aussi une mémoire automatique.
Cadrez les règles là où elles s'appliquent
Un monorepo avec un site vitrine, une app et une bibliothèque n'a pas un seul jeu de conventions. Les fichiers imbriqués sont lus pour les sessions dans leur dossier ou en dessous. Si le dépôt a déjà un AGENTS.md, Claude Code peut le lire à la place.
Ce qui n'y a pas sa place
- Tout secret. C'est un fichier du dépôt, lu en contexte à chaque session.
- Un changelog. Il croît sans fin et ne change aucune décision.
- Tout ce qu'un outil peut imposer. Une règle de format appartient au formateur, une règle de lint au linter.
- Des instructions qui ne s'appliquent que parfois. Ce sont des skills, pas un coût permanent.
Le flux environnant est dans construire un site avec Claude Code, et les pièges à consigner sont rassemblés dans que vérifier avant de croire que l'agent l'a construit.
Un exemple concret, abrégé
Ce qui suit est la forme d'un vrai fichier, sans les spécificités du projet. Le point important est le ratio : presque chaque ligne est une règle avec une conséquence.
- Pile : le framework et sa version majeure, l'approche de style, et une liste de ce qu'il ne faut pas installer.
- Contenu : chaque chaîne vit dans la couche de données. Un titre codé en dur est un défaut.
- Affirmations : aucune statistique, nom de client ou témoignage sans source nommée. Si un chiffre manque, supprimez la phrase.
- Style : la ponctuation et les mots proscrits, énoncés une fois.
- Vérification : la commande exacte qui prouve qu'un changement marche, et la note qu'un build propre ne le prouve pas.
- Pièges : les bugs déjà produits par ce dépôt, chacun avec le contrôle qui l'attrape.
Écrivez des règles qui échouent bruyamment
Une règle formulée comme préférence est mise en balance et perd parfois. Une règle formulée comme condition, non. Là où une règle peut devenir mécanique, sortez-la du fichier vers un contrôle qui fait échouer le build.
Les réglages sont un levier distinct
Les instructions ne sont pas des permissions. Quelles commandes peuvent s'exécuter sans demander appartient aux réglages, pas à une prose qui demande poliment.
Deux endroits que ce fichier atteint et qu'on oublie facilement. Un sous-agent démarre avec vos instructions chargées à moins de les omettre délibérément: une règle écrite ici gouverne donc aussi le travail délégué, ce qui compte plus qu'il n'y paraît dès qu'on découpe un gros build. Ce qu'il faut déléguer aux sous-agents montre où passe cette frontière. Et une règle qui doit tenir plutôt qu'être simplement lue n'a pas sa place dans de la prose, l'argument de les hooks qui verrouillent un dépôt de site.
