Écrire un CLAUDE.md parfait : les 10 règles d'or

Le CLAUDE.md, c'est quoi exactement ?

C'est un fichier à la racine de votre projet que Claude Code lit automatiquement au démarrage de chaque session. Pensez-le comme un brief permanent pour votre copilote IA. Plus il est précis, meilleur est le résultat.

Les 10 règles d'or

1. Soyez spécifique sur la stack

Ne dites pas "React app". Dites "Next.js 16.1.6, App Router, RSC, Turbopack". Les versions comptent. Claude Code doit savoir si vous êtes sur Prisma 6 ou 7, si vous utilisez Zod 3 ou 4.

2. Documentez les gotchas

Chaque stack a ses pièges. proxy.ts au lieu de middleware.ts en Next.js 16, m au lieu de motion avec LazyMotion, listez-les explicitement.

3. Montrez l'architecture avec un arbre

Un schéma src/ avec 3 niveaux de profondeur vaut mieux que 10 paragraphes d'explication. Claude Code comprend les structures de dossiers instantanément.

4. Incluez les commandes

pnpm dev, pnpm build, npx prisma generate... Claude Code a besoin de savoir comment lancer, builder et tester votre projet.

5. Définissez le data flow

Server Component → Service → Prisma → HTML. Action → Validate → Service → Revalidate. Ces patterns doivent être explicites.

6. Séparez les règles par contexte

Utilisez .claude/rules/ pour des règles spécifiques : animations.md, domains.md, components.md. Ça garde le CLAUDE.md principal concis.

7. Précisez la langue

"UI en français, code en anglais", simple mais critique pour un projet multilingue.

8. Listez les variables d'environnement

Pas les valeurs, juste les noms. Claude Code doit savoir quelles env vars existent sans les voir.

9. Restez concis

Un CLAUDE.md de 200 lignes est plus efficace qu'un de 2000. Claude Code a un contexte limité, chaque ligne doit apporter de la valeur.

10. Mettez à jour régulièrement

Votre projet évolue, votre CLAUDE.md aussi. Après chaque migration ou changement d'architecture, mettez-le à jour.

Template de démarrage

Commencez avec ces sections : Project, Stack, Commands, Architecture, Key Patterns, Critical Rules, Environment Variables. Ajoutez des détails au fur et à mesure que vous découvrez des patterns récurrents.