Construire : le fichier CLAUDE.md

Objectifs

À l’issue de cette leçon, vous serez capable de :

• Rédiger un CLAUDE.md qui donne à Claude ce qu’il faudrait à un nouvel arrivant
• Le versionner et le faire évoluer comme du code

Ce qui change

Le savoir d’une équipe vit souvent dans les têtes et sur des wikis : conventions, commandes, architecture, erreurs fréquentes. Le CLAUDE.md en fait un fichier que l’agent lit au début de chaque session, entretenu par toute l’équipe et complété à chaque erreur.

Pour démarrer

• Prérequis : aucun.
• Infrastructure : un dépôt, Claude Code installé, et un ingénieur qui connaît bien la base de code.

Mise en œuvre

1. Lancez /init dans le dépôt : Claude génère un premier CLAUDE.md à partir de ce qu’il trouve.
2. Réduisez-le à ce dont un nouvel arrivant aurait besoin le premier jour : les commandes de build, de test et de lint, les conventions qui comptent, et ce que Claude se trompe régulièrement à faire.
3. Enregistrez-le dans Git, à la racine du dépôt : toute l’équipe partage la même version, et ses modifications sont relues comme du code.
4. Quand Claude répète une erreur, ajoutez la règle qui l’aurait évitée.
5. Gardez-le sous une page : Claude le lit en entier au début de chaque session, et ce qui est périmé occupe du contexte pour rien. La documentation de Claude Code vise moins de 200 lignes par fichier, et conseille de déplacer les consignes propres à une partie du code dans des règles par chemin, chargées seulement quand Claude y travaille.

Exemple

# Espace adhérent Mutualis
## Commandes
- Build : make build
- Tests : make test (unitaires), make itest (intégration, nécessite docker)
- Lint : make lint (lancé en CI ; corriger avant de pousser)
## Conventions
- remb-api est en Python 3.12 et FastAPI ; l'espace adhérent en TypeScript et React.
- Chaque point d'accès a un test dans remb-api/tests.
- Les dates traversent l'API au format ISO 8601, jamais en texte mis en forme.
## Architecture
- intent/ contient intent.md, spec.md et plan.md pour chaque changement.
- Seul remb-api parle à l'ancien système de remboursement ; il accepte 50 requêtes par seconde : mettre en cache, ne jamais interroger en boucle.
## Ce que Claude se trompe à faire
- Ne pas journaliser les corps de requête ou de réponse dans remb-api : ils peuvent contenir des données de santé.
- Ne pas monter les versions des dépendances : l'équipe plateforme en est responsable.

Gouvernance

Le CLAUDE.md est versionné : les consignes que suit l’agent sont relisibles et auditables. Ses modifications apparaissent dans l’historique Git, et les responsables du code les approuvent en revue de pull request.

Mesurer

• Indicateur avancé : la fréquence à laquelle Claude répète une erreur que le CLAUDE.md aurait dû éviter ; les corrections du fichier se suivent dans l’historique Git.
• Indicateur retardé : le délai avant la première pull request fusionnée d’un nouveau membre de l’équipe.

Le regard de Corsen — Un CLAUDE.md est lu par l’agent à chaque session : traitez-le comme une configuration de sécurité. Exigez une revue par les responsables du code (fichier CODEOWNERS) pour toute modification, et ne laissez jamais un secret ou une adresse interne sensible y figurer.

À vous de jouer

Votre CLAUDE.md en une page. Lancez /init dans un dépôt que vous connaissez bien, puis coupez tout ce dont un nouvel arrivant n’aurait pas besoin le premier jour. Ajoutez une rubrique « Ce que Claude se trompe à faire » avec deux erreurs que vous avez déjà vues. Faites relire le fichier en pull request, comme du code, et tenez pendant deux semaines la liste des erreurs répétées : chacune doit devenir une ligne du fichier.

Sources officielles : The CLAUDE.md (Claude Academy) · The AI-native SDLC playbook — Stage 3: Build · Memory (CLAUDE.md)

Points clés à retenir

• CLAUDE.md donne à Claude ce qu’il faudrait à un nouvel arrivant : commandes, conventions, architecture, erreurs fréquentes
• /init pour démarrer, puis réduire à moins d’une page
• Versionné à la racine du dépôt, relu comme du code, complété à chaque erreur répétée