Notre CLAUDE.md fait 162 lignes. Voici ce qu'il contient — et ce que nous avons supprimé.

Le fichier le plus coûteux de votre dépôt que vous ne connaissiez pas

Si vous utilisez Claude Code, votre CLAUDE.md à la racine du projet est le fichier le plus coûteux de votre dépôt. Non pas à cause de l’espace disque — parce que chaque octet se charge dans le contexte à chaque démarrage de session, sans chargement différé. Les skills se chargent progressivement. Les outils MCP peuvent être différés. CLAUDE.md est simplement là, toujours chargé, occupant continuellement votre fenêtre de contexte.

Le nôtre faisait 820 lignes. Nous l’avons réduit à 162 sans perdre un seul garde-fou. Cet article détaille exactement ce qui est sorti, ce qui est resté et les trois patterns qui ont fait le travail.

Chiffres clés : 820 → 162 lignes, ~8 000 → ~1 200 tokens, et une part de ~12 % → ~0,75 % de la fenêtre de contexte de 200 K.

Pourquoi CLAUDE.md mérite son propre article

Dans notre article plus large sur l’optimisation des tokens, MCP Tool Search était le levier le plus important. CLAUDE.md est le deuxième. La recherche sur les grands frameworks Claude Code rapporte que les configurations racine optimisées atteignent une réduction de 54–62 % de la surcharge de base, et un anti-pattern documenté — un CLAUDE.md de 2 800 lignes — gaspillait environ 62 % des tokens par session.

Le mécanisme en est la raison. Le contenu CLAUDE.md à chaque niveau de la hiérarchie se charge sans condition :

Fichiers de politique d’entreprise
CLAUDE.md à la racine du projet
~/.claude/CLAUDE.md au niveau utilisateur
Surcharges locales au projet
Tout fichier importé via la syntaxe @chemin/vers/fichier (récursif jusqu’à 5 niveaux de profondeur)

Tout le reste que Claude Code fait autour du contexte — chargement progressif des skills, MCP Tool Search, isolation des sous-agents — est conçu pour contourner la taxe du toujours-chargé. CLAUDE.md est la seule chose que vous payez inconditionnellement, à chaque tour.

Notre avant : 820 lignes, environ 12 % du contexte

Notre CLAUDE.md original ressemblait à un manuel d’entreprise. Il documentait chaque skill que nous utilisions, chaque étape de porte de publication, chaque nuance de notre configuration WordPress Coding Standards, chaque convention de nommage pour les composants React, chaque règle de portée des assets admin. C’était du matériel de référence genuinement utile. Il était aussi chargé dans chaque session, y compris les sessions qui n’avaient rien à voir avec la plupart de son contenu.

Voici un bilan approximatif de ce qu’il contenait :

Section	Lignes	Tokens approx.	Fréquence de charge justifiée ?
Carte de l’espace de travail et structure du projet	90	900	Oui — contexte pour toute session
Architecture et stack technique	60	600	Oui
Règles de confidentialité (non négociables)	40	400	Oui — invariants critiques
Descriptions par skill (30+ entrées)	180	1 800	Non — les skills individuels se chargent à la demande
Protocoles de workflow détaillés	200	2 000	Non — nécessaires uniquement pendant ce workflow
Standards de test en détail	120	1 200	Non — pertinents seulement pour les sessions d’écriture de tests
Description complète de la porte de publication	80	800	Non — vit dans le skill de publication
Notes de dépannage	50	500	Non — rarement nécessaires

Tout ce qui est marqué « Non » payait une taxe à chaque session pour être disponible dans une fraction d’entre elles. C’est environ 6 300 tokens de gaspillage — environ 3 % de l’ensemble de la fenêtre de contexte, en permanence.

Notre après : 162 lignes, environ 0,75 %

Le nouveau CLAUDE.md couvre la même surface avec trois patterns : une table de déclenchement, des fichiers CLAUDE.md imbriqués et des règles à portée de chemin.

Pattern 1 : La table de déclenchement de skills

Au lieu de documenter chaque skill avec un paragraphe, nous avons remplacé ~30 descriptions par skill par une seule table de consultation :

## Skill triggers
| Trigger keywords | Skill | Domain |
|------------------|-------|--------|
| sprint, backlog, iteration | pm-sprint-plan | PM |
| story, acceptance criteria | pm-story-write | PM |
| deploy, release, ship | statnive-release | Dev |
| security, audit, CVE | sec-audit-remediate | Security |
| wireframe, mockup | ux-design | UX |
| benchmark, performance | wp-performance | WP |

La recherche sur les grands frameworks rapporte que ce pattern coûte ~800 tokens contre 3 000+ pour une prose verbeuse par skill. Le routage de Claude fonctionne toujours correctement car les mots-clés de déclenchement sont ce qu’il fait réellement correspondre — la prose longue « quand utiliser ce skill et quand ne pas l’utiliser » que nous écrivions n’aidait jamais au routage, elle remplissait juste le contexte.

Tout le contenu détaillé « quand utiliser / quand ne pas utiliser » vit dans les fichiers SKILL.md individuels, chargés uniquement lorsque Claude y route. La table de déclenchement est l’index ; les skills sont les chapitres.

Pattern 2 : Fichiers CLAUDE.md imbriqués pour les règles de domaine

Voici la propriété critique que la plupart des développeurs manquent : les fichiers CLAUDE.md imbriqués dans les sous-répertoires sont chargés de façon différée. Ils entrent dans le contexte uniquement lorsque Claude lit des fichiers dans ces sous-arborescences.

La structure de notre dépôt ressemble maintenant à ceci :

statnive-workflow/
├── CLAUDE.md                    # 162 lignes — global uniquement
├── statnive/
│   ├── CLAUDE.md                # PHP / WordPress plugin conventions
│   ├── src/
│   └── tests/
├── statnive-website/
│   └── CLAUDE.md                # Astro / MDX / frontend conventions
└── jaan-to/
    └── CLAUDE.md                # AI framework conventions

Lorsque nous écrivons du PHP pour le plugin, statnive/CLAUDE.md se charge automatiquement et intègre nos notes WordPress Coding Standards, la règle d’application de $wpdb->prepare() et la règle de portée des assets admin. Lorsque nous écrivons du contenu de blog MDX, statnive-website/CLAUDE.md se charge avec les conventions Astro et les notes de style maison. Ni l’un ni l’autre n’interfère avec l’autre.

Ce pattern a supprimé environ 2 200 tokens de contenu « parfois pertinent seulement » de la racine.

Pattern 3 : Règles à portée de chemin dans `.claude/rules/`

Le troisième mécanisme est .claude/rules/ — des fichiers de règles avec un frontmatter YAML qui peuvent déclarer les chemins auxquels ils s’appliquent :

---
paths: ["statnive-website/src/**/*.tsx", "statnive-website/src/**/*.astro"]
---
Use Tailwind utilities scoped under `#statnive-app`. Never import the default
Tailwind bundle — it restyles the WordPress admin chrome.

Les règles avec un champ paths: se chargent conditionnellement — uniquement lorsque Claude travaille avec des fichiers correspondants. Les règles sans champ paths: se chargent inconditionnellement, donc nous les limitons à une poignée stricte (règles de confidentialité, règles de sécurité, conventions de commit).

Nous avons déplacé environ 1 800 tokens de conventions spécifiques au framework hors du CLAUDE.md racine vers des règles à portée de chemin sous .claude/rules/. Elles se déclenchent toujours de façon fiable quand c’est pertinent, et ne coûtent rien quand ce ne l’est pas.

L’anti-pattern que nous avons supprimé : les `@-imports`

Notre CLAUDE.md original avait trois @-imports :

@jaan-to/docs/best-practices.md
@jaan-to/context/tech.md
@jaan-to/outputs/ROADMAP.md

Cela semble ordonné. C’est un piège. La syntaxe @ charge récursivement le contenu complet de chaque fichier cible à chaque session, jusqu’à cinq niveaux de profondeur. Nos trois imports seuls ajoutaient environ 6 000 tokens de surcharge permanente pour du contenu dont le modèle avait besoin peut-être une fois sur vingt sessions.

Nous avons remplacé chacun par un pointeur :

For architectural context see `jaan-to/context/tech.md`.
For the current roadmap see `jaan-to/outputs/ROADMAP.md`.

Claude lit ces chemins quand il en a réellement besoin — via l’outil Read, à la demande. Coût de base nul, même résultat pratique.

Ce qui reste dans le fichier racine

Après les suppressions, le CLAUDE.md racine de 162 lignes contient exactement :

Section	Lignes	Pourquoi elle est restée
Philosophie produit (8 principes issus de la recherche)	28	Oriente chaque décision ; doit influencer toutes les sessions
Carte de l’espace de travail	18	Orientation en un coup d’œil, chargée pour toute session
Règles de confidentialité (non négociables)	16	Invariants critiques — Cookie, IPs brutes, salts, SHA-256
Règle de portée des assets admin	22	Nous a déjà causé des problèmes, s’applique largement
Politique de commit (la mention co-authored-by est interdite)	8	Convention git globale
Règle de workflow `/simplify`	18	Application de notre porte de qualité
Table de déclenchement de skills	32	Remplace ~30 sections verbeux par skill
Chemins clés (pointeurs, pas d’imports)	20	Références en une ligne vers les docs

Tout le reste a été déplacé dans des CLAUDE.md imbriqués, des règles à portée de chemin ou des corps de skill individuels.

Ce que nous n’avons pas optimisé

Mises en garde honnêtes, même pattern que le reste de la série :

Le ~/.claude/CLAUDE.md au niveau utilisateur échappe à notre contrôle. Nos ingénieurs ont chacun leur propre configuration globale, et celles-ci se chargent en plus du fichier projet. La recherche signale cela comme une source courante de surcharge cachée — un CLAUDE.md global contenant « se souvenir d’exécuter les tests avant de committer » en plus d’un workflow au niveau projet qui fait exactement cela coûte des tokens sans ajouter de signal. Nous avons demandé aux membres de l’équipe d’auditer les leurs. Le vôtre mérite probablement un coup d’œil.
Nous n’avons pas encore de porte CI sur la taille du CLAUDE.md racine. La recherche suggère de faire échouer la PR si CLAUDE.md racine + tout @-import dépasse ~2 500 tokens. Nous appliquons avec des vérifications ponctuelles /context. Une porte CI est sur la feuille de route.
Les marqueurs IMPORTANT et YOU MUST sont tentants. Anthropic exécute en interne les fichiers CLAUDE.md à travers leur améliorateur de prompts et utilise des marqueurs d’emphase pour les règles critiques. Nous les utilisons avec parcimonie — chacun est une surcharge permanente, donc nous les réservons aux règles de confidentialité (pas de Cookie, pas d’IPs brutes) et à la politique de commit (pas de mention co-authored-by).

L’étape de mesure que vous ne pouvez pas sauter

Si vous auditez votre propre CLAUDE.md, la seule commande qui compte est /context. Exécutez-la au tout début d’une nouvelle session, avant toute invite. Elle décompose votre utilisation du contexte par source : invite système, outils, mémoire (c’est CLAUDE.md), métadonnées de skills et schémas d’outils MCP.

Chiffres que nous visons pour une session avec une fenêtre de 200 K :

Source	Cible	Plafond strict
CLAUDE.md racine + règles non délimitées	≤ 1 500 tokens	2 500
Métadonnées de skills	≤ 2 500 tokens	5 000
Schémas d’outils MCP (avec Tool Search)	≤ 3 000 tokens	8 000
Stdout de hooks (SessionStart, UserPromptSubmit)	0 tokens	300 par hook

Si votre /context dépasse l’un de ceux-ci de plus de ~50 %, vous avez le même problème que nous avions. Les correctifs sont les trois patterns ci-dessus plus MCP Tool Search.

Pourquoi cela importe pour les personnes qui utilisent Statnive

Notre CLAUDE.md est public dans le dépôt Statnive sur GitHub — pour la même raison que notre pipeline de tests est public. Une configuration racine compacte signifie des sessions plus rapides, des exécutions moins coûteuses et un modèle qui lit vraiment ce qui importe au lieu de se noyer dans du matériel de référence « toujours disponible, rarement nécessaire ». Cette efficacité se traduit par ce qui compte pour nos utilisateurs : un plugin qui est souvent livré et reste sous son budget de Tracker de 5 Ko.

Essayez Statnive

Des analytics WordPress axées sur la confidentialité, construites par une équipe qui prend les budgets de tokens aussi au sérieux que les budgets de performance. Installez Statnive gratuitement depuis WordPress.org — vos données restent sur votre serveur, nos pratiques d’ingénierie restent sur GitHub pour que chacun puisse les auditer.