Le template CLAUDE.md le plus complet pour 2026

Pourquoi 90% des CLAUDE.md ne servent à rien

La plupart des CLAUDE.md trouvés sur GitHub en 2026 sont des fichiers de 200 lignes qui répètent ce que Claude sait déjà : "ce projet utilise React", "on commit en feature branches". Ces fichiers ne font que brûler des tokens à chaque session pour zéro valeur ajoutée.

Un CLAUDE.md utile fait exactement l'inverse : il contraint le comportement de Claude sur les choses qu'il ne peut PAS deviner — la voix éditoriale spécifique à ton projet, les anti-patterns issus de tes incidents passés, les paths absolus de tes fichiers de référence, les conventions internes que personne d'autre n'utilise.

Sur les projets que je maintiens, le passage d'un CLAUDE.md générique à un CLAUDE.md ciblé a réduit la consommation de tokens de 30% en moyenne et coupé les hallucinations (Claude qui invente des paths, qui ignore une convention) de 85%. La différence vient de 4 sections critiques que personne n'écrit correctement.

La structure obligatoire en 11 sections

Le template ci-dessous suit l'ordre exact dans lequel Claude doit lire — du plus contextuel (mission, source de vérité) au plus opérationnel (workflows, garde-fous). Cet ordre n'est pas négociable : changer l'ordre = Claude lit la mauvaise chose en premier et applique les mauvaises règles.

1. Mission — une phrase max. Si tu n'y arrives pas, Claude non plus.
2. Source de vérité — les fichiers à lire AVANT toute action.
3. Stack technique — choix + raison (pas juste la liste).
4. Conventions de code — voix, style, naming.
5. Anti-patterns — les NEVER explicites, avec contexte.
6. Skills Claude Code disponibles dans ce projet.
7. Workflows types — bug fix, nouvelle feature, refacto.
8. Budget tokens — règles d'optimisation explicites.
9. Garde-fous sécurité — secrets, auth, input validation.
10. Sub-agents recommandés — quand déléguer.
11. Onboarding — pour Claude qui démarre une session.

Les 3 anti-patterns qui flinguent ton budget tokens

1. Le CLAUDE.md narratif (description sans contraintes)

Si ton CLAUDE.md ressemble à une page Notion qui raconte ce que fait l'app, c'est inutile. Claude lit le code lui-même — il a besoin de contraintes opérationnelles, pas d'une présentation marketing du projet. Règle simple : si un humain peut lire ton fichier en l'enlevant et que ton code marche pareil, tu as un narratif, pas un guide.

2. Les anti-patterns implicites

Écrire "on suit la convention X" sans dire ce qu'il ne faut JAMAIS faire = Claude essaie quand même. Tu dois être explicite : "NEVER mock the DB in integration tests (incident postmortem Q4 2025)". La précision du pourquoi permet à Claude de juger les cas limites.

3. Pas de section budget tokens

Sans règles explicites du type "toujours préférer Edit/Write/Read aux Bash + cat/sed/awk", Claude prend par défaut des chemins coûteux en tokens. Une session de 200K tokens devient 80K avec les bonnes règles. C'est la section qui justifie à elle seule de copier ce template.

Pas envie d’attendre le mail ? Essaie la communauté : 7 jours offerts →

Comment je structure le mien chez WhatSetter

Le CLAUDE.md de WhatSetter pèse 420 lignes et couvre l'intégralité de la stack — Appwrite pour le backend, Claude Code pour le développement, Resend pour le mail transactionnel. Mais ce qui le rend efficace, c'est moins son contenu que son ordre de lecture.

Les 4 premières sections (mission, source de vérité, stack, conventions) prennent 15% du fichier mais résolvent 80% des questions que Claude se pose au début d'une session. Les sections opérationnelles (workflows, anti-patterns, budget tokens) sont au milieu — c'est là que Claude revient quand il hésite. Les annexes (onboarding, git workflow) sont en bas — Claude y va seulement quand il en a besoin.

Cet ordre suit la pyramide d'attention de Claude : il lit le début intégralement, scan le milieu, ignore la fin sauf instruction explicite. Si tu mets tes règles critiques en bas, il les loupe. Inverser n'est pas une option — c'est la différence entre un CLAUDE.md qui marche et un qui ne fait rien.

Le déclic à avoir pour 2026

En 2026, Claude Code a passé un cap : les sub-agents, les skills et les MCP servers sont devenus la norme, pas l'exception. Un CLAUDE.md qui ne mentionne pas explicitement quand déléguer à un sub-agent (par exemple general-purpose pour les recherches multi-fichiers) laisse Claude faire le travail lui-même — et c'est 5× plus coûteux en tokens.

Le template que je t'envoie inclut cette section "Sub-agents recommandés" avec une table de décision : quand utiliser general-purpose, code-reviewer, bug-analyzer, Explore, Plan. C'est probablement la section qui te fera le plus économiser de tokens dans tes 30 prochaines sessions.