AIDive

Pack vidéo

Supprimez votre CLAUDE.md, mesuré : tableaux d'ablation, checklist et sources

11 min de lecture

TL;DR

  • Sur un vrai dépôt avec un CLAUDE.md de 177 lignes, 3 skills et 1 hook, tout supprimer n'a cassé qu'une seule règle, dans une seule situation : la règle i18n sur un fichier tout neuf. Toutes les autres conventions ont tenu parce que le code environnant les enseignait déjà.
  • Le fichier a coûté 4 à 14 % des tokens lus sur les tâches où le résultat était identique, environ un dollar sur dix. Les 32 % d'économie affichés viennent surtout de la tâche où le fichier poussait le modèle à faire plus de travail.
  • Les skills et le hook ne coûtent rien de mesurable : les skills ne se chargent qu'à l'appel et aucun n'a été appelé, le hook injecte une seule phrase.
  • L'aperçu d'architecture de 82 lignes n'a rien apporté sur la question d'architecture : six réponses, toutes justes, avec ou sans le fichier.
  • « Supprimer », dans les mots d'Anthropic, veut dire ablater et passer à la divulgation progressive, pas effacer. Gardez les règles que le code ne peut pas enseigner, déplacez le reste vers des fichiers de règles et des skills, et transformez les règles non négociables en hooks.
  • Deux répétitions par configuration, c'est un plancher, pas un verdict : les écarts par tâche sous 15 % restent dans le bruit d'une exécution à l'autre.

Ce que disent les mesures

La conférence qui fait réagir tout le monde dit deux choses, et la seconde est oubliée. Boris Cherny confirme sur scène que Claude Code a supprimé 80 % de son prompt système, et il décrit la méthode : supprimer tout le prompt système, puis le réintroduire ligne par ligne pour mesurer l'impact de chacune s2. Le passage « every 6 months » se situe entre 00:06:58 et 00:07:05, et la formulation est « really do recommend », pas « strongly recommend » s1. Deux phrases qu'on lui attribue largement ne figurent pas dans la conférence : « context, goals and a definition of done » (la formule réelle la plus proche, à 15:22, est « describe the task, the guardrails, the exit criteria ») et « 64 agents ». Il dit « eleven days » et, quand on lui demande un nombre d'agents, « I'm not sure » s2. Le chiffre de 64 vient de l'article sur la réécriture de Bun : « 64 Claudes running for 11 days », environ 165 000 $ au tarif API, 9 milliards de tokens d'entrée non cachés, 690 millions de tokens de sortie et 72 milliards de lectures de tokens d'entrée en cache s14.

Ce qui rend tout cela mesurable, c'est le chargement. CLAUDE.md et les fichiers de règles sont injectés à chaque tour ; les skills ne se chargent que lorsqu'ils sont appelés. La doc sur la mémoire contient aussi la consigne de taille que tout le monde paraphrase : « target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence. » s4. La version écrite du conseil par Anthropic présente le CLAUDE.md centralisé comme un mythe et renvoie vers la divulgation progressive et la mémoire automatique s3.

La seule étude contrôlée avant la nôtre est l'article de l'ETH sur AGENTS.md : 138 issues réparties sur 12 dépôts, et « providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average ». Les fichiers écrits par les développeurs font mieux que ceux générés par un LLM de 7 % en moyenne, et les instructions qui nomment des outils précis aident s5.

Deux données sur le contenu de ces fichiers et la façon dont ils sont lus. Sur 28 721 dépôts et 165 063 fichiers, le fichier d'instructions médian contient 50 éléments de contenu, dont 12 sont de vraies directives ; l'auteur en conclut que seuls 27 % du fichier font ce que vous croyez s8. Dans une expérience contrôlée avec deux instructions réellement en conflit, déplacer une seule règle du haut du fichier vers le bas fait varier d'environ 90 points la fréquence à laquelle le modèle l'applique, de presque jamais à presque toujours s9. Le même éditeur trace la ligne que suit notre expérience : l'ablation n'est pas la suppression, et les hooks sont de l'application de règles, ils n'expirent pas avec une mise à jour de modèle s7.

Deux a priori informels concordent avec notre résultat. Un CLAUDE.md de 1 000 lignes comparé à une version réduite d'environ 20 lignes, sur les mêmes issues GitHub avec le même modèle : l'architecture tenait, les règles maison cassaient s6. Un commentateur qui a tout déplacé vers la divulgation progressive rapporte un contexte chargé automatiquement passé d'environ 35k à environ 4,5k tokens par session, sans aucune connaissance supprimée s11. Pour évaluer des ablations de skills, il existe un outil : le --ablate de caliper couvre les skills et les serveurs MCP et son compare rapporte le taux de réussite, les tokens et le temps réel ; le remplacement du CLAUDE.md reste manuel s16.

Mesures

Protocole : un dépôt privé Expo / React Native (1 021 fichiers suivis), un CLAUDE.md de 177 lignes, 7 243 caractères, environ 1 800 tokens, 3 skills, 4 commandes slash, 1 hook PreToolUse. Modèle fixé sur claude-opus-5 pour chaque exécution, Claude Code 2.1.278, claude -p en mode headless, --max-turns 40, répertoire de config utilisateur vide, pas de MCP, clone neuf réinitialisé avant chaque exécution. Cinq tâches courantes (nouveau composant, modification d'un composant, refactor d'helpers partagés, persistance d'un champ de store, explication d'un chemin de données), ablation une pièce à la fois. 44 exécutions, 38,97 $ au tarif API, 92 minutes de temps agent. Notation : les règles maison du dépôt sur les lignes ajoutées, tsc --noEmit, eslint, réponses notées à la main.

Qualité, ce qui a cassé :

config exécutions d'édition violations des règles maison nouvelles erreurs tsc erreurs eslint
A complet 8 0 0 0
B sans CLAUDE.md 8 1 (nouveau titre écrit en dur, pas de .content.ts) 0 0
C sans skills 4 0 0 0
D sans hook 4 0 0 0
E rien 8 2 (titre écrit en dur deux fois, pas de .content.ts) 0 0

Coût par exécution, moyenne sur les exécutions de la config (tokens = lectures du cache, le contexte relu à chaque tour) :

config exécutions $ / exécution tours / exécution tokens lus / exécution
A complet 10 0.95 25.6 829k
B sans CLAUDE.md 10 0.74 21.9 568k
C sans skills 5 0.96 28.2 819k
D sans hook 5 0.96 27.8 851k
E rien 10 0.85 25.7 655k

Par tâche, de A à B (moyenne de 2 exécutions chacune) :

tâche A $ B $ coût tokens lus
T1 nouveau composant 1.72 0.96 -44% -61%
T2 modification de composant 1.49 1.26 -15% -15%
T3 refactor 0.64 0.63 -1% -5%
T4 store 0.57 0.53 -6% -4%
T5 question 0.34 0.31 -9% -14%
les 10 exécutions 9.51 7.40 -22% -32%

Lecture des tableaux. Sans le CLAUDE.md, 3 exécutions sur 4 du nouveau composant ont écrit le titre en simple chaîne ; avec lui, 4 sur 4 ont créé le .content.ts avec EN et FR. Sur la tâche de modification, toutes les configs, même E, ont mis la nouvelle chaîne dans un .content.ts : les fichiers voisins portaient la convention. Tout le reste a tenu dans les 44 exécutions : 0 import relatif, type et non interface dans six modifications du fichier de types, des design tokens dans chaque diff, 0 couleur hexadécimale, pas de fichier barrel. Une instruction que personne n'a pu suivre : le fichier demande d'importer theme depuis @design-tokens, un alias qui n'existe pas dans tsconfig.json ; aucune exécution, dans aucune config, ne l'a utilisé, soit 1 800 tokens lus pour rien à chaque session. L'économie de T1 vient de l'exécution moins chère qui fait moins de travail. La variance d'une exécution à l'autre est plus grande que la plupart des effets de config : T1 avec la config complète a coûté 2,11 $ puis 1,33 $. Un contrôle avec le graphe de code de 333 Mo présent a retrouvé les chiffres de la config complète (1,59 $ contre 1,72 $ sur T1, 0,38 $ contre 0,34 $ sur T5) : le bloc du graphe et le hook n'ont rien changé de mesurable.

À faire lundi

  • Comptez votre CLAUDE.md : lignes, caractères, et nombre de lignes qui sont de vraies directives (Always, Never, Use, Prefer). Le reste est du contexte que le modèle relit à chaque tour.
  • Choisissez une convention par section et vérifiez si un fichier voisin la montre déjà. Si trois fichiers du dossier suivent la règle, la ligne est candidate à la suppression.
  • Trouvez la règle que le code ne peut pas enseigner sur un fichier tout neuf (i18n, télémétrie, en-têtes de licence, une étape d'enregistrement obligatoire). Gardez-la, écrivez-la en une ligne et placez-la près du haut.
  • Essayez chaque chemin d'import et chaque commande que votre fichier nomme. Un alias mort ou un script renommé est une instruction que personne ne peut suivre.
  • Déplacez les longs aperçus d'architecture et les guides d'installation vers un fichier de règles ou un skill chargé à la demande, puis comparez le contexte chargé automatiquement avant et après.
  • Transformez vos deux ou trois règles non négociables en hook ou en règle de lint. L'application d'une règle ne dépend pas de la lecture d'un paragraphe par le modèle.
  • Lancez vos deux tâches les plus fréquentes deux fois avec le fichier et deux fois sans, sur un modèle fixé, puis lisez les tokens et le diff. Deux répétitions disent où regarder, pas quoi conclure.

Aller plus loin

  • La conférence elle-même, pour la méthode plutôt que la petite phrase : supprimer, puis réintroduire ligne par ligne s2.
  • L'ensemble des résultats de l'article, y compris le constat que les fichiers écrits par les développeurs battent les fichiers générés de 7 % et que nommer les outils aide s5.
  • La position d'une règle comme variable : l'écart d'environ 90 points et la façon dont le modèle tranche en silence entre instructions contradictoires s9.
  • L'anatomie, sur 30k dépôts, d'un fichier d'instructions : 50 éléments, 12 directives, et ce que sont les 38 autres s8.
  • Le guide HumanLayer pour écrire un bon CLAUDE.md et le fil qui le conteste s10.
  • Le fil « MUST use agent, ignorée 80 % du temps » : un argument pour les hooks là où la prose échoue s12.
  • Le fil « Claude Code now ignores everything », utile pour distinguer la dérive du modèle des conflits d'instructions s13.
  • caliper, pour évaluer les ablations de skills et de MCP avec taux de réussite, tokens et temps réel s16.

Sources

FAQ

Dois-je supprimer mon CLAUDE.md ?

Pas à l'aveugle. Sur notre dépôt, la seule perte a été une règle sur les nouveaux fichiers ; tout ce que le code démontrait déjà a tenu sans le fichier. Ablatez une section à la fois et gardez ce qui change le résultat.

Pourquoi le fichier a-t-il économisé 32 % de tokens s'il n'a coûté que 4 à 14 % ?

Parce que l'agrégat est dominé par la tâche du nouveau composant, où le fichier poussait le modèle à écrire un second fichier en deux langues. L'exécution la moins chère faisait moins. Sur les tâches au résultat identique, l'économie était de 4 à 14 %.

Les skills et les hooks coûtent-ils des tokens à chaque tour ?

Les skills ne se chargent qu'à l'appel, donc un skill non appelé ne coûte rien ; le hook injecte une seule phrase. Supprimer les deux n'a changé aucun chiffre dans nos exécutions. Les fichiers de règles et le CLAUDE.md sont ceux qui sont relus à chaque tour.

Deux exécutions par configuration, est-ce suffisant ?

Non. Deux répétitions situent l'effet, elles ne le mesurent pas. Notre config complète a coûté 2,11 $ puis 1,33 $ sur la même tâche, donc les écarts par tâche sous 15 % sont dans le bruit.