Bonnes pratiques du fichier CLAUDE.md

À quoi sert un fichier CLAUDE.md

Un fichier CLAUDE.md se trouve à la racine de votre dépôt et est chargé automatiquement dans le contexte de Claude Code à chaque session. Voyez-le comme le document d'accueil que vous aimeriez que chaque nouveau contributeur lise avant de toucher au code — sauf que celui-ci est lu à chaque fois, sans exception.

L'erreur courante est de le traiter comme un README. Un README explique le projet à des humains qui le liront une seule fois. Un CLAUDE.md donne à l'agent les règles qu'il doit suivre pour chaque tâche. La nuance est subtile, mais elle change la façon d'écrire.

Restez court et précis

Chaque ligne de votre CLAUDE.md rivalise avec la tâche réelle pour capter l'attention du modèle. Un fichier de 2 000 lignes rempli de bonnes intentions vaut moins qu'un fichier de 60 lignes contenant les cinq commandes et les trois conventions qui comptent vraiment.

Préférez le concret à l'abstrait :

Mauvais : « Suivre de bonnes pratiques de test et viser la qualité. »
Bon : « Lancer npm run test avant chaque commit. Placer les specs en *.spec.ts. »

Si une règle ne peut pas être appliquée, elle n'a pas sa place ici.

Mettez les commandes en premier

La chose la plus utile à ajouter, ce sont les commandes exactes pour compiler, tester et linter. Les agents gaspillent des tours à deviner si c'est npm test, yarn test ou just test. Dites-le une bonne fois :

npm run dev     # démarrer le serveur de développement
npm run build   # build de production (vérifie aussi les types)
npm run test    # lancer la suite de tests

Cette seule section évite plus d'allers-retours que n'importe quoi d'autre.

Écrivez les règles en « toujours » et « jamais »

Claude suit bien les instructions impératives. Énoncez clairement les non-négociables :

Jamais de commit direct sur la branche par défaut — créez d'abord une branche.
Toujours valider les entrées des Server Actions avec Zod avant de les utiliser.
Jamais exposer la clé de rôle de service au client.

Des affirmations nettes et vérifiables valent mieux que des suggestions floues. « Essayez d'éviter » sera ignoré sous pression ; « jamais » ne le sera pas.

Séparez les grands ensembles de règles en fichiers

Quand vos conventions grandissent, ne mettez pas tout dans un seul fichier. Découpez les règles par domaine (tests, sécurité, base de données, UI) dans des fichiers distincts et laissez le CLAUDE.md racine y renvoyer. Chaque fichier reste ainsi ciblé et plus facile à maintenir — vous modifiez les règles de sécurité sans défiler devant les conventions CSS.

Laissez-le évoluer

Les meilleurs fichiers CLAUDE.md sont des documents vivants. Quand vous surprenez l'agent à refaire la même erreur deux fois, c'est un signal : ajoutez une ligne pour qu'il n'y ait pas de troisième fois. En quelques semaines, le fichier converge exactement vers les garde-fous dont votre projet a besoin.

Merci de votre lecture — à bientôt.