J'ai testé des dizaines de configurations Claude Code.
Le seul truc qui a vraiment changé mon output : un fichier de 60 lignes qui s'appelle CLAUDE.md.
Gardez précieusement en Signet 🔖
Voici exactement comment il fonctionne, pourquoi la plupart des gens le ratent complètement, et le template complet que tu peux copier aujourd'hui :
Ce que personne ne te dit sur Claude Code
Avant ton premier prompt. Avant la moindre ligne de code. Avant que quoi que ce soit se passe dans ta session.
Claude lit un fichier. Un seul.
CLAUDE.md.
Et il le traite comme la vérité absolue pour toute la session. Pas comme une suggestion. Pas comme un contexte parmi d'autres. Comme le brief définitif qui cadre chaque décision qu'il va prendre.
C'est pour ça que ce fichier est la variable la plus sous-estimée de tout le stack Claude Code.
La plupart des gens n'en ont pas du tout. Et ceux qui en ont un ont fait l'une de ces deux erreurs : soit le fichier est vide de substance, soit c'est 300 lignes de "sois un senior engineer expérimenté qui pense étape par étape."
Les deux sont inutiles. Pour des raisons différentes.
Pourquoi la plupart des CLAUDE.md ne fonctionnent pas : les 3 vraies raisons
Raison 1 : Trop long
Claude peut suivre environ 150 à 200 instructions de manière fiable sur une session. C'est une contrainte structurelle, pas une question de bonne volonté.
Problème : le system prompt interne de Claude Code contient déjà environ 50 instructions. Ça veut dire que ton CLAUDE.md dispose réellement de 100 à 150 slots d'instructions avant que Claude commence à en laisser tomber.
Si ton fichier fait 200 lignes, Claude n'ignore pas tes règles exprès. Il les oublie mécaniquement. Tu n'as pas un problème de compliance. Tu as un problème de budget d'attention.
Raison 2 : Mauvais contenu
La majorité des CLAUDE.md sont remplis de choses que Claude peut déduire tout seul ou qui ne changent pas son comportement de manière mesurable.
"Agis comme un ingénieur senior." → Claude sait déjà ce que ça veut dire et ça n'ancre aucun comportement précis. "Pense étape par étape." → C'est dans son training. Tu gaspilles une ligne. "Écris du code propre et maintenable." → Aucun critère concret. Claude ne sait pas ce que "propre" veut dire dans ton contexte spécifique.
Chaque ligne qui n'empêche pas une erreur précise et concrète est une ligne volée aux instructions qui comptent vraiment. Le test est simple : si tu supprimes cette ligne, est-ce que Claude va se tromper sur quelque chose de spécifique ? Si la réponse est non, la ligne ne devrait pas être là.
Raison 3 : Zéro hiérarchie
La plupart des gens ignorent qu'il existe trois niveaux d'instructions dans Claude Code, et ils foutent tout au même endroit.
~/.claude/CLAUDE.md → Global (s'applique à tous tes projets)
.claude/CLAUDE.md → Projet (partagé avec l'équipe, dans git)
./CLAUDE.local.md → Local (overrides perso, gitignored)
Le niveau global est fait pour les règles que tu répéterais dans chaque projet. Le niveau projet est fait pour le contexte spécifique à ta stack et à ton équipe. Le niveau local est fait pour tes préférences personnelles qui n'ont pas à être partagées.
Utiliser les trois niveaux correctement, c'est ce qui garde chaque fichier court, focalisé et réellement efficace. Tout mettre dans un seul fichier, c'est construire un entonnoir pour noyer tes règles importantes sous du bruit.
Les 5 sections qui composent un CLAUDE.md efficace
Après avoir épluché des dizaines de CLAUDE.md en production projets open-source, docs officielles d'Anthropic, dépôts de bonnes pratiques de la communauté
voici les 5 sections que tous les fichiers efficaces ont en commun:
Section 1 : Les commandes critiques
Claude démarre chaque session sans savoir comment builder ton projet, lancer tes tests ou corriger les erreurs de lint. Il va deviner. Et ses devinettes vont te coûter des tours.
Dis-lui exactement quoi taper :
## Commandes
- Build :
pm run build\
- Dev :
pm run dev\
- Test fichier seul :
pm test -- path/to/file\
- Test complet :
pm test\
- Lint + fix :
pm run lint:fix\
- Type check :
px tsc --noEmit\
Court. Précis. Directement utilisable.
Sans cette section, Claude va essayer npm test quand ton projet tourne sur pnpm vitest. Il va débugger pendant trois tours un problème de commande qui n'allait jamais fonctionner. Trois tours que tu aurais pu utiliser sur du vrai travail.
Section 2 : La carte d'architecture
Claude commence chaque session avec zéro connaissance de ton codebase. Zéro. Il ne sait pas où vit ta logique métier. Il ne sait pas si tes composants sont censés être stateless. Il ne sait pas que tes routes API ne doivent pas contenir de business logic.
Donne-lui une carte :
## Architecture
- src/lib/services/ → toute la logique métier
- src/components/ → composants UI stateless uniquement
- src/lib/store/ → état global (Zustand)
- src/app/api/ → routes API, aucune logique métier ici
- Accès BDD uniquement via Server Actions ou routes API
Pas un listing exhaustif de ton arborescence. Juste assez pour que Claude sache où les choses vivent et, surtout, où elles ne doivent PAS aller.
Cette distinction... où ça va vs où ça ne va pas... est ce qui évite les erreurs d'architecture les plus fréquentes.
Section 3 : Les règles dures
C'est la section la plus importante de tout le fichier. Sans exception.
Chaque règle ici doit répondre à une seule question : "Si je supprime cette ligne, est-ce que Claude va faire une erreur concrète ?"
Si oui → la règle reste. Si non → elle n'a rien à faire là.
Exemple de règles à haute valeur :
## Règles
- JAMAIS committer de fichiers .env ou secrets
- Tous les appels async doivent être wrappés dans un try/catch
- Composants fonctionnels uniquement, zéro class component
- Préfixes de commit obligatoires : feat:, fix:, docs:, refactor:
- Tout PR doit passer
pm run verify\ avant merge
- Export statique uniquement, pas de SSR (déployé sur S3)
- IMPORTANT : lancer le type check après chaque modification de code
Deux choses à noter sur cette liste.
Premièrement, les règles négatives sont aussi importantes que les règles positives. "Ne jamais committer de fichiers .env" est une règle qui ne semble évidente que jusqu'au jour où Claude le fait. Mets-la.
Deuxièmement, les marqueurs d'emphase comme IMPORTANT ou YOU MUST fonctionnent réellement.
Ce n'est pas anecdotique. Anthropic le confirme dans sa propre documentation : ajouter IMPORTANT ou YOU MUST devant une règle améliore mesurably l'adhérence de Claude à cette règle.
Utilise-les avec parcimonie : réserve-les aux règles qui ont les conséquences les plus graves si elles sont ignorées.
Reste sous 15 règles dans cette section. Au-delà, tu dilues l'attention sur celles qui comptent.
Section 4 : Les préférences de workflow
Tu as déjà vécu ça. Tu demandes à Claude de corriger une ligne. Il te réécrit trois fichiers, renomme tes fonctions et refactorise une classe qui n'avait rien à voir avec ta demande.
Cette section empêche ça :
## Workflow
- Poser des questions clarifiantes avant de commencer les tâches complexes
- Faire des changements minimaux, ne pas refactoriser du code non lié
- Lancer les tests après chaque changement, corriger les échecs avant de continuer
- Créer des commits séparés par changement logique, pas un commit géant
- En cas d'incertitude entre deux approches, expliquer les deux et me laisser choisir
Chaque ligne ici répond à une douleur concrète. Le commit géant de 47 fichiers. La réécriture complète non demandée. La décision architecturale que Claude prend seul alors qu'il aurait dû te demander.
Section 5 : Ce qu'il ne faut PAS mettre dans ton CLAUDE.md
Cette section est aussi importante que les autres. Peut-être plus.
## À ne PAS inclure :
- Instructions de personnalité ("sois un senior engineer")
- Règles de formatage que ton linter gère déjà
- Imports @ qui embarquent des docs entières dans chaque session
- Règles dupliquées (si le global dit "lance les tests", le projet ne le répète pas)
- Tout ce que Claude apprend seul via l'auto-memory
Ce dernier point est largement sous-estimé.
Claude maintient ses propres notes dans ~/.claude/projects/<project>/memory/. Lance /memory / dans ta session pour voir ce qu'il a déjà appris sur ton projet. Après quelques sessions, tu vas souvent réaliser que Claude a déjà capturé des informations que tu allais écrire à la main dans ton CLAUDE.md.
Ne gaspille pas tes instructions limitées sur des choses que Claude a retenu tout seul.
Le template complet sous 60 lignes, prêt à utiliser
Supprime les sections qui ne s'appliquent pas à ton projet. L'objectif n'est pas de tout remplir. L'objectif est de ne garder que ce qui change le comportement de Claude de manière mesurable.
Les lignes qui ont eu le plus d'impact sur mon output résultats concrets
Après avoir testé des dizaines de configurations, voici les cinq lignes qui ont fait la différence la plus visible :
IMPORTANT : lancer le type check après chaque modification de code → Empêche Claude de livrer du code avec des types cassés qu'il ne détecte pas sans être explicitement invité à vérifier.
Faire des changements minimaux, ne pas refactoriser du code non lié → Empêche la réécriture complète et non demandée de fichiers entiers.
Créer des commits séparés par changement logique, pas un seul commit géant → Empêche le commit monstre illisible de 47 fichiers mélangés.
En cas d'incertitude entre deux approches, expliquer les deux et me laisser choisir → Empêche Claude de prendre seul des décisions architecturales qui auraient dû t'appartenir.
Export statique uniquement, pas de SSR → Empêche Claude d'ajouter du code serveur dans un projet déployé en statique sur S3.
Ce que ces cinq lignes ont en commun : chacune empêche une erreur précise, fréquente, et coûteuse en temps de debug.
C'est le test ultime pour chaque ligne de ton CLAUDE.md.
L'erreur fondamentale et pourquoi elle est si répandue
Les gens traitent leur CLAUDE.md comme une liste de vœux ou un prompt de personnalité.
"Sois senior." "Sois minutieux." "Pense comme un expert."
Ce n'est pas un brief. C'est de la pensée magique.
Ton CLAUDE.md doit être un document technique, pas un discours de motivation. Stack, commandes, architecture, règles concrètes, workflow. Tout le reste est du bruit qui concurrence les instructions qui comptent vraiment.
Garde le fichier sous 80 lignes. Révise-le à chaque fois que Claude fait une erreur que tu aurais pu prévenir.
Et surtout : comprends ce que ce fichier devient dans le temps.
Un bon CLAUDE.md au premier mois te fait gagner du temps sur chaque session. Au troisième mois, il a capturé tes conventions et ta stack de manière suffisamment précise pour que Claude travaille presque comme un membre de l'équipe.
Au sixième mois, il contient chaque erreur que Claude a jamais faite sur ce projet et les empêche toutes automatiquement.
Le fichier se capitalise. Il s'améliore à chaque correction. Il devient progressivement le meilleur brief de onboarding que tu aies jamais écrit.
Pas pour Claude. Pour toi.
