CLAUDE.md : bonnes pratiques et exemple annoté complet

CLAUDE.md est le fichier le plus coûteux de votre dépôt. Pas en octets. En répétition. Tout ce que vous y mettez est chargé dans le contexte de Claude au début de chaque session, puis accompagne chacun des messages que vous envoyez ensuite. Un CLAUDE.md obèse est une taxe que vous payez des centaines de fois par jour sans vous en rendre compte.

Tester des setups Claude est notre métier chez SkillProof, et nous avons désormais lu plus de fichiers CLAUDE.md que nous ne voudrions l'admettre. La plupart se trompent de la même façon : ils traitent le fichier comme un fourre-tout pour tout ce que l'auteur a un jour voulu faire savoir à Claude. Philosophie de code, préférences de ton, un guide de style complet, trois paragraphes sur la prudence. Le tout chargé, en permanence, pour chaque requête, y compris celle où vous demandez à Claude de renommer une variable.

Ce guide est notre tentative d'y remédier. À quoi sert vraiment CLAUDE.md, un exemple complet annoté que vous pouvez adapter, ce qu'il faut déplacer vers des skills, et l'arithmétique qui explique pourquoi tout cela compte.

Ce qu'est CLAUDE.md et quand il se charge

CLAUDE.md est le fichier de mémoire de projet de Claude Code. Quand vous démarrez une session dans un répertoire, Claude Code remonte depuis votre répertoire de travail à la recherche de fichiers CLAUDE.md et charge ce qu'il trouve dans le contexte système. Votre fichier global ~/.claude/CLAUDE.md se charge aussi, dans chaque projet. Les fichiers placés dans des sous-répertoires se chargent quand Claude travaille sur des fichiers de ces sous-répertoires.

Ce que les gens ratent : ce n'est pas une lecture unique. Les modèles de langage sont sans état, donc le contexte complet, CLAUDE.md compris, est envoyé avec chaque requête de la conversation. Posez quarante questions dans une session et le fichier est transmis quarante fois. Le cache de prompt adoucit le coût en dollars, et nous arriverons aux vrais chiffres, mais rien n'adoucit le coût en attention. Chaque token de CLAUDE.md est un token qui dispute au code lui-même l'attention du modèle.

Voilà le prix. Il vous achète quelque chose de réel : Claude démarre chaque session en connaissant déjà vos commandes de build, vos particularités d'architecture et les mines de votre base de code. Personne n'a à coller « on utilise pnpm, pas npm » pour la neuvième fois. La question n'est jamais de savoir s'il faut un CLAUDE.md. C'est de savoir ce qui mérite d'y figurer.

La règle d'or : les faits dans CLAUDE.md, les comportements dans les skills

Voici la thèse de tout cet article, et le filtre unique qui répare la plupart des mauvais fichiers :

CLAUDE.md est fait pour les faits propres à ce projet. Les skills sont faits pour les comportements réutilisables.

Un fait propre à ce projet : « les prix sont stockés en centimes entiers ». Claude ne peut pas le deviner. Aucune intelligence générale ne le fait surgir de nulle part, et se tromper corrompt des données. Sa place est dans CLAUDE.md, chargé en permanence, parce qu'il concerne presque toute modification qui touche à l'argent.

Un comportement réutilisable : « pour une revue de code, vérifier d'abord la gestion d'erreurs, puis la sécurité, puis le nommage ». Ce n'est pas un fait sur votre projet. C'est une procédure, elle s'applique à tous les projets que vous toucherez un jour, et elle n'est pertinente que lorsque vous faites réellement une revue. Mettez-la dans CLAUDE.md et vous la payez pendant chaque message de commit, chaque retouche CSS, chaque « que fait cette fonction ». Mettez-la dans un skill et elle vous coûte une ligne de métadonnées jusqu'au moment où une revue a effectivement lieu, où les instructions complètes se chargent à la demande.

La plupart des gens entassent tout dans CLAUDE.md parce que c'est le fichier qu'ils connaissent. Il est là, il fonctionne visiblement, et le coût est invisible parce qu'aucune facture n'indique jamais « vous avez payé votre guide de style 4 000 fois ce mois-ci ». Mais le coût est réel, et le tri devient presque mécanique dès qu'on pose deux questions sur chaque instruction. Est-elle vraie uniquement pour ce projet ? Est-elle pertinente pour la plupart des requêtes ? Deux oui : CLAUDE.md. Tout le reste : un skill, ou la corbeille.

Il y a une seconde raison à ce tri, qui n'a rien à voir avec les tokens. Les instructions d'un fichier toujours chargé se font concurrence. Nous avons vu un CLAUDE.md de 2 000 mots où la règle réellement importante (« ne jamais lancer db:push contre staging ») dormait au onzième paragraphe, sous un sermon sur le code propre. Claude suit les longues listes d'instructions comme les humains : les points saillants se diluent dans le remplissage qui les entoure. Les fichiers courts sont obéis. Les fichiers longs sont survolés.

Un exemple de CLAUDE.md annoté pour une web app de taille moyenne

Voici un exemple complet pour une boutique Next.js fictive mais réaliste. Les annotations expliquent pourquoi chaque section mérite sa place permanente dans le contexte. Le tout fait environ 350 mots, soit à peu près 500 tokens, et nous soutenons que rien n'y est superflu.

# Acme Storefront

Next.js 14 (App Router) + TypeScript. Postgres via Prisma. Deployed on Vercel.
<!-- One line of stack. Claude infers most of this from package.json anyway;
     this just saves it the lookup. Do not write paragraphs here. -->

## Commands
- `pnpm dev` — local server on :3000 (needs `docker compose up db` first)
- `pnpm test` — unit tests (Vitest). Integration: `pnpm test:int` (slow, needs db)
- `pnpm lint && pnpm typecheck` — run both before calling any task done
- Migrations go through `pnpm db:migrate`. NEVER `db:push` outside local.
<!-- Commands earn their place because Claude runs them dozens of times per
     session, and a wrong guess (npm vs pnpm) wastes a round-trip every time.
     The db:push line is here because the failure is irreversible. -->

## Architecture facts you can't guess
- `src/app` is routes only. All logic lives in `src/modules/<domain>`.
- API routes are thin wrappers over `src/modules/*/service.ts`. No logic in routes.
- Auth is Clerk, but `userId` in services is OUR internal id, not Clerk's.
  Map with `getInternalUser()`.
- Prices are integer cents everywhere. Formatting lives in `lib/money.ts`.
- Feature flags come from `flags.ts`, not env vars.
<!-- The test for this section: would a skilled new hire get it wrong on
     day one? The Clerk id mismatch has caused real bugs; that is exactly
     the kind of fact worth paying for on every request. -->

## Conventions that differ from defaults
- Named exports only. Legacy violations exist in `src/legacy`; don't add new ones.
- Server components by default. `"use client"` needs a comment saying why.
- Zod schemas live next to services; infer types from them, never hand-write both.
<!-- Only conventions that DIFFER from what Claude would do anyway.
     "Use TypeScript strict mode" when tsconfig already says so is a wasted line. -->

## Gotchas
- `src/legacy/*` is frozen. Don't refactor it or import from it in new code.
- CI runs Node 20. `pnpm test:int` fails on 22; use `nvm use` first.
<!-- Each line here represents an hour someone actually lost. -->

## Definition of done
Lint, typecheck, and unit tests pass, and you state which of them you ran.
<!-- One sentence. Not a philosophy of quality. -->

Remarquez ce qui est absent. Pas de « écris du code propre et maintenable ». Pas d'instructions de ton. Pas d'explication de ce qu'est Next.js. Pas de règles de lint que le linter applique déjà mécaniquement. Chaque ligne est soit une commande que Claude exécutera, soit un fait qu'il ne peut pas déduire, soit une limite dont le franchissement coûte de l'argent ou des heures bien réels.

Ce qu'il faut déplacer vers des skills

Si votre CLAUDE.md actuel fait 1 500 mots, l'excédent tombe généralement dans quelques catégories reconnaissables, et chacune a un foyer en forme de skill. Quelques exemples tirés de notre propre catalogue, tous installés et testés sur machines vierges avant référencement :

Le cérémonial git. Nommage des branches, format des messages de commit, modèles de description de PR, quand squasher. C'est du comportement, identique d'un projet à l'autre, et pertinent seulement au moment de commiter. Le skill git-workflow que nous avons testé couvre exactement ce périmètre, et le sortir de CLAUDE.md économise typiquement 200 à 400 mots de texte toujours chargé.

Les checklists de revue. Les instructions « quand je demande une revue, vérifie X puis Y » sont le squatteur classique de CLAUDE.md. Elles sont longues, procédurales et dormantes 95 % du temps. code-review-checklist ne charge sa checklist que lorsqu'une revue a lieu, ce qui est tout l'intérêt du format skill.

La discipline de débogage. Des instructions comme « reproduire avant de corriger, énoncer son hypothèse, vérifier après » décrivent une méthodologie, pas votre projet. systematic-debugging empaquette cette méthodologie et reste hors du contexte tant que vous ne chassez pas un bug.

La règle générale : si vous pouviez copier le paragraphe dans le CLAUDE.md d'un autre projet sans le modifier, ce n'est pas un fait sur votre projet et il n'a rien à y faire. Extrayez-le. Écrire votre propre skill prend environ vingt minutes avec notre guide, et ce sont les vingt minutes au meilleur levier pour quiconque a un CLAUDE.md qui dépasse un écran.

Les anti-patterns que nous voyons en boucle

Nous passons en revue beaucoup de setups, et les cinq mêmes échecs reviennent sans cesse.

Le roman. Un CLAUDE.md de 3 000 mots qui se lit comme un manuel d'ingénierie. Quelqu'un a eu une mauvaise expérience, a ajouté un paragraphe, en a eu une autre, en a ajouté un autre, et n'a jamais rien supprimé. Le fichier ne fait que grossir. Au-delà du coût en tokens, ces fichiers enterrent les deux règles qui comptent vraiment sous vingt qui ne comptent pas, et l'observance de Claude chute pour toutes à la fois.

Les commandes périmées. Le fichier dit npm run test:unit, le script a été renommé pnpm test il y a huit mois, et Claude lance désormais avec assurance une commande qui échoue, lit l'erreur, fouille package.json et se rattrape. À chaque session. Vous payez pour la mauvaise documentation, puis vous payez encore pour que Claude la contourne. Un CLAUDE.md faux est pire que pas de CLAUDE.md du tout, parce que Claude lui fait confiance.

Les règles de lint dupliquées. « Guillemets simples. Pas de variables inutilisées. Longueur de ligne max 100. » Votre configuration ESLint applique déjà tout cela mécaniquement, avec une couverture meilleure que ne le sera jamais l'attention d'un LLM. Répéter en prose des règles appliquées par la machine est du pur gaspillage. La seule exception : les règles que l'outillage ne peut pas attraper, comme « ne pas importer depuis src/legacy », qui méritent réellement d'être écrites.

La section « sois utile ». « Écris du code propre. Réfléchis bien avant de modifier. Sois rigoureux mais concis. » Nous voyons une variante de cela dans à peu près la moitié des fichiers que nous examinons, et cela ne produit rien. Claude essaie déjà. Les instructions d'ambiance sans contenu testable sont la première chose à supprimer, et leur seul effet mesurable est les tokens qu'elles brûlent.

L'autobiographie. De longues descriptions de ce que fait le produit, de qui sont les utilisateurs, de la mission de l'entreprise. Parfois, un fait produit compte pour les décisions de code (« nos utilisateurs sont sur des connexions rurales lentes, la taille du bundle est une vraie contrainte »). Gardez cette phrase-là. Coupez le pitch deck.

Le calcul des tokens

Faisons l'arithmétique que tout le monde saute, parce que ce sont les chiffres qui nous ont rendus minimalistes.

Un CLAUDE.md de 3 000 mots représente environ 4 000 tokens. Il accompagne chaque requête, donc une session de travail de 40 messages le transmet 40 fois : 160 000 tokens d'entrée en une session qui sont votre fichier mémoire, pas votre code ni votre conversation. Travaillez cinq sessions par jour et vous déplacez 800 000 tokens de CLAUDE.md quotidiens. Sur un mois de 22 jours, environ 17,6 millions.

Le cache de prompt sauve l'essentiel du coût en dollars, et soyons honnêtes là-dessus. L'entrée mise en cache sur Sonnet coûte un dixième du prix de base, donc ces 17,6 M de tokens reviennent à quelques dollars par mois si le cache reste chaud, plutôt 50 $ s'il ne l'est pas. Agaçant, pas ruineux.

Le coût que le cache ne sauve pas, c'est le contexte. La fenêtre de contexte de Claude Code est finie, et les longues sessions se terminent déjà en compaction, où la conversation est résumée et le détail se perd. Un résident permanent de 4 000 tokens signifie que vous atteignez la compaction plus tôt, à chaque session, pour toujours. Il dégrade aussi l'attention bien avant toute limite dure : les modèles suivent démontrément mieux les instructions quand elles sont moins nombreuses à se faire concurrence. La différence entre un fichier de 500 tokens et un de 4 000 n'est pas 3 500 tokens. C'est de savoir si le modèle se soucie encore de votre règle « ne jamais toucher à staging » au message 35.

Refaites les mêmes calculs sur l'exemple allégé ci-dessus : 500 tokens, 40 messages, cinq sessions, 22 jours. Environ 2,2 M de tokens par mois, un huitième de la version obèse, avec les règles importantes debout dans une pièce dégagée. Nous avons rédigé le playbook complet de réduction des coûts dans notre guide des coûts en tokens, et l'allégement de CLAUDE.md y est systématiquement le gain le moins cher.

Projet ou global : la répartition avec ~/.claude/CLAUDE.md

Vous avez deux fichiers, et les ennuis commencent quand le contenu atterrit dans le mauvais.

~/.claude/CLAUDE.md est global. Il se charge dans chaque projet, il ne doit donc contenir que des choses vraies partout : « j'utilise pnpm sur tous mes projets personnels », « réponds en anglais même si mes prompts sont parfois en russe », « ne jamais commiter sans qu'on te le demande ». Gardez-le sous dix lignes. Chaque ligne y est multipliée sur l'ensemble de votre travail, son budget doit donc être le plus serré.

<project>/CLAUDE.md est le fichier de projet, versionné dans git, partagé avec les collègues et la CI. Des faits sur cette base de code, dans l'esprit de l'exemple ci-dessus. Parce qu'il est partagé, les préférences personnelles n'y ont pas leur place ; c'est le rôle de CLAUDE.local.md ou du fichier global.

Les CLAUDE.md de sous-répertoires sont l'étage intermédiaire sous-utilisé. Un packages/api/CLAUDE.md avec des faits propres à l'API ne se charge que lorsque Claude touche à ce package. Si le fichier racine de votre monorepo contient des sections qui ne concernent qu'un seul workspace, les descendre d'un niveau est une économie de tokens gratuite, sans aucune perte d'information.

Une idée reçue à tuer : mettre une chose dans plusieurs de ces fichiers ne fait pas que Claude la suive plus fort. Cela allonge le fichier. Un seul foyer par fait.

Le garder à jour

CLAUDE.md pourrit plus vite que la documentation classique, parce que rien ne casse visiblement quand il est faux. Les tests échouent bruyamment. Un fichier mémoire périmé égare discrètement le modèle, qui se rattrape discrètement, et vous payez discrètement les deux.

Notre rituel est ennuyeux et prend dix minutes par mois. Ouvrez le fichier. Pour chaque commande, exécutez-la réellement. Pour chaque fait énoncé, demandez-vous s'il est encore vrai et si Claude s'est trompé ce mois-ci à cause de lui. Supprimez au moins une ligne ; il y en a toujours une, et si vous ne la trouvez pas, vos critères pour « mériter sa place » ont glissé. Puis vérifiez la longueur : un écran est la cible, deux écrans le plafond, et au-delà vous n'éditez plus, vous extrayez vers des skills.

Le meilleur déclencheur de mise à jour n'est pourtant pas le calendrier. C'est le moment où Claude fait quelque chose de travers parce que le fichier l'a induit en erreur. Corrigez le fichier dans le même geste que le code. Traitez les bugs de CLAUDE.md comme des bugs, parce qu'ils ont le même comportement de récidive : non corrigés, ils reviennent à la session suivante.

FAQ

Quelle longueur pour un CLAUDE.md ?

Moins de 500 mots pour la plupart des projets, moins de 1 000 pour un monorepo vraiment compliqué. Notre test de travail : s'il ne tient pas sur un écran, quelque chose dedans est du comportement déguisé en fait, et ce quelque chose relève d'un skill. L'exemple de cet article fait environ 350 mots et couvre une vraie application de taille moyenne.

Quelle est la différence entre CLAUDE.md et un skill ?

Le mode de chargement. CLAUDE.md est chargé en entier, toujours, pour chaque requête. Un skill n'expose qu'une description d'une ligne jusqu'à ce qu'une tâche lui corresponde, puis se charge à la demande. CLAUDE.md doit donc contenir les faits dont vous avez constamment besoin, et les skills les procédures dont vous avez besoin occasionnellement. Notre guide des skills couvre la mécanique.

Faut-il commiter CLAUDE.md dans git ?

Oui. C'est de la documentation partagée, et les sessions Claude de vos collègues profitent des mêmes faits que les vôtres. Gardez les préférences personnelles dans CLAUDE.local.md (gitignoré) ou dans votre fichier global plutôt que de les imposer à l'équipe.

Peut-on utiliser des CLAUDE.md imbriqués dans des sous-répertoires ?

Oui, et dans les monorepos vous devriez. Claude Code charge le fichier d'un sous-répertoire quand il travaille sur des fichiers qui s'y trouvent. Le fichier racine reçoit les faits valables pour tout le dépôt, packages/api/CLAUDE.md les faits de l'API, et les projets mono-package peuvent se passer entièrement d'imbrication.

Alléger CLAUDE.md change-t-il vraiment le comportement de Claude, ou seulement le coût ?

Les deux, et le comportement est le plus gros gain. Le suivi des instructions se dégrade à mesure que leur nombre augmente ; un fichier court avec cinq règles nettes est obéi plus fiablement qu'un long avec trente. Les économies de tokens sont la partie mesurable, et nos classements efficacité suivent les skills qui aident le plus sur ce front, mais l'amélioration de l'observance est ce que vous remarquerez en premier.

Une dernière opinion : les meilleurs CLAUDE.md que nous ayons vus ont tous été édités par suppression. Personne n'en écrit un excellent le premier jour. Vous en écrivez un médiocre, observez où Claude trébuche, ajoutez le fait qui aurait évité le faux pas, et coupez une ligne de remplissage pour le payer. Six semaines de ce régime battent n'importe quel template, y compris le nôtre.