Pourquoi CLAUDE.md coûte-t-il aussi cher ?
CLAUDE.md coûte aussi cher parce qu'il se trouve dans la partie du prompt qui est renvoyée à chaque tour, et qu'il se situe au tout début du préfixe du cache — donc un fichier obèse ou instable est refacturé à chaque requête pendant toute la session, et un fichier qui change d'une session à l'autre invalide discrètement le prompt caching, vous faisant payer le plein tarif au lieu du taux de cache-read d'≈10%. C'est le fichier de votre dépôt qui a le plus d'impact sur le coût en tokens, et presque personne ne le traite ainsi. Je passe mes journées à construire des outils autour des tokens, et CLAUDE.md est le but contre son camp le plus fréquent que je rencontre. Les gens se demandent sans fin s'il faut lire un fichier avechead ou cat, puis collent un guide de style maison de 900 lignes dans CLAUDE.md et se demandent où est passée la facture. Le grand levier ne se cache pas. C'est le fichier que vous avez écrit exprès.
C'est une ramification de Comment réduire l'usage de tokens de Claude Code. Si vous voulez l'ensemble des leviers — lectures de fichiers, output filtering, élagage MCP — commencez par là. Cet article creuse l'un d'eux en profondeur, car il mérite son propre traitement.
Comment CLAUDE.md entre-t-il réellement dans le contexte ?
CLAUDE.md entre dans le contexte comme partie de la couche système/instructions qui préfixe la conversation, et surtout il n'est pas lu une fois puis oublié — son contenu participe au préfixe que le modèle retraite à chaque tour de la boucle agentique. Cela compte à cause du fonctionnement de l'agentic coding. À chaque étape, l'agent renvoie l'historique accumulé plus les instructions permanentes, et le modèle relit le tout pour produire l'action suivante. Donc tout ce qui est épinglé près du début — votre CLAUDE.md compris — est payé de nouveau à chaque tour. Un CLAUDE.md de 4 000 tokens sur une session de 40 tours, ce n'est pas 4 000 tokens. C'est 4 000 tokens multipliés par quarante tours de traitement en entrée, modulés par la qualité de tenue de votre cache. Ce qui nous amène à la partie que la plupart des gens manquent : le cache.Quel rapport entre CLAUDE.md et le prompt caching ?
CLAUDE.md fait partie du préfixe du cache, donc sa stabilité fait la différence entre payer le plein tarif d'entrée et n'en payer qu'environ un dixième. Le prompt caching vous offre un taux de cache-read réduit — environ 10% du prix d'entrée normal — mais seulement sur le plus long préfixe identique entre les requêtes. Dès l'instant où votre préfixe change, le cache se rompt à ce point et tout ce qui suit est refacturé au plein prix d'entrée. CLAUDE.md vit tout au début de ce préfixe. Deux conséquences en découlent, et elles tirent dans le même sens :- Un CLAUDE.md stable est un atout de cache. Si le fichier est identique octet pour octet d'une session à l'autre, il reste à l'intérieur du préfixe mis en cache et se refacture au taux de cache-read. Pas cher.
- Un CLAUDE.md instable est une boule de démolition pour le cache. Modifiez-le — ajoutez une note « penser à lancer la migration », collez la liste de tâches du jour — et vous avez changé le préfixe. Le cache rate désormais au niveau de CLAUDE.md, et tout ce qui se trouve en aval est refacturé au plein prix, pas seulement les octets que vous avez modifiés.
Quel est le coût réel en dollars ?
Le coût réel dépend du modèle, de la taille du fichier, du nombre de tours et de votre taux de cache-hit — mais un exemple chiffré rend l'ordre de grandeur évident. Voici les prix de liste publiés au moment de l'écriture (par million de tokens, MTok) :| Modèle | Entrée / MTok | Sortie / MTok | Cache read (≈10% de l'entrée) |
|---|---|---|---|
| Claude Opus 4.8 | $5 | $25 | ≈ $0.50 |
| Claude Sonnet 4.6 | $3 | $15 | ≈ $0.30 |
| Claude Haiku 4.5 | $1 | $5 | ≈ $0.10 |
| GPT-5.5 | $5 | $30 | ≈ $0.50 |
- Entièrement mis en cache (fichier stable, cache-hit à chaque tour) : 4 000 tokens × 40 tours = 160 000 lectures de tokens au taux de cache d'≈$0.30/MTok ≈ $0.048. Une erreur d'arrondi. Ignorez-la.
- Jamais mis en cache (vous avez modifié le fichier en cours de session, ou il a changé depuis la dernière fois, donc c'est de l'entrée au plein prix) : 160 000 tokens à $3/MTok ≈ $0.48. Dix fois plus, pour le même fichier.
Trop gros, c'est combien ?
Trop gros, c'est le point où CLAUDE.md cesse d'être un ensemble de règles durables et devient une base de connaissances. Il n'y a pas de ligne magique, mais une heuristique utile : si vous ne pouvez pas justifier chaque section comme « une convention qui sera encore vraie dans trois mois », elle n'a rien à y faire. Les fichiers qui explosent ont tendance à accumuler les mêmes déchets :- De la documentation collée. Références d'API, docs de frameworks, changelogs de bibliothèques. L'agent peut aller les chercher à la demande ; les épingler à chaque tour est la manière coûteuse d'être paresseux.
- De l'état de tâche transitoire. « Migration du module d'auth en cours. » « TODO : réparer le test instable. » C'est spécifique à la session, ça change constamment, et chaque modification fait exploser votre cache.
- De longues énumérations. Une liste de 60 lignes de chaque répertoire du dépôt, ou de chaque variable d'environnement. L'agent peut découvrir la structure avec la semantic code search ; il n'a pas besoin d'une carte maintenue à la main renvoyée quarante fois.
- De la sur-instruction défensive. Paragraphe après paragraphe de « toujours faire X, ne jamais faire Y, attention à Z ». Passé un certain point, cela cesse d'orienter le comportement et ne fait que gonfler le préfixe.
Que devrais-je faire concrètement ?
Traitez CLAUDE.md comme un contrat cache-stable, pas comme un brouillon. Concrètement :- Auditez la longueur. Passez votre CLAUDE.md dans un compteur de tokens. S'il dépasse quelques milliers de tokens, ce nombre est votre surcoût par tour — allez le couper.
- Expulsez le transitoire. Tout ce qui est vrai aujourd'hui mais pas le mois prochain quitte le fichier. L'état de tâche va dans votre gestionnaire de tickets ou dans le chat lui-même, pas dans les instructions permanentes.
- Arrêtez de le modifier en cours de session. Chaque sauvegarde pendant une session active casse le cache pour tout le reste de cette session. Regroupez les changements de CLAUDE.md entre les sessions, où le coût est un seul démarrage à froid au lieu d'une pénalité par tour.
- Repoussez la découverte vers la récupération. Remplacez « voici toute la disposition du dépôt » par le fait de laisser l'agent trouver les choses à la demande. C'est vraiment de cela que parle le context engineering — fournir le bon contexte par tour au lieu de tout le contexte à chaque tour.
- Mesurez, ne devinez pas. Surveillez vos chiffres d'input tokens et de cache-hit avant et après. Un CLAUDE.md plus léger et plus stable devrait se traduire par un taux de cache-hit plus élevé, immédiatement.
Foire aux questions
CLAUDE.md est-il relu à chaque tour ?
En pratique, oui. CLAUDE.md est chargé dans la couche d'instructions permanentes, et cette couche fait partie du préfixe que le modèle retraite à chaque tour de la boucle. Ce n'est pas une lecture unique dont vous payez le coût une seule fois — ses tokens participent à l'entrée de chaque tour, ce qui est précisément pourquoi la taille et la stabilité comptent autant. Le facteur atténuant est le prompt caching : si le préfixe est identique d'un tour à l'autre, ces relectures sont facturées à environ 10% du plein prix d'entrée.Pourquoi modifier CLAUDE.md coûte-t-il plus cher que la modification elle-même ?
Parce que le caching se base sur le plus long préfixe identique, et que CLAUDE.md se situe près du début de ce préfixe. Quand vous le changez, le cache cesse de correspondre au point du changement, donc non seulement les octets modifiés mais tout ce qui les suit dans le prompt se refacture au plein prix d'entrée pour le reste de la session. La modification est bon marché ; l'invalidation du cache qu'elle déclenche est le coût réel. C'est l'argument pour regrouper les changements de CLAUDE.md entre les sessions plutôt qu'en plein vol.Devrais-je simplement supprimer CLAUDE.md pour économiser des tokens ?
Non — cela revient à jeter le signal avec le bruit. Un bon CLAUDE.md vous fait économiser des tokens ailleurs : il empêche l'agent de redécouvrir votre commande de build, votre lanceur de tests et vos conventions par tâtonnement, chacun coûtant plus qu'une ligne d'instruction serrée. L'objectif est un fichier léger et stable, pas un fichier vide. Gardez les règles durables ; expulsez les déversements de documentation et les notes de tâche du jour.Est-ce que cela s'applique à Cursor, Copilot et aux autres agents ?
Oui. Le mécanisme est universel à tout agent qui épingle des instructions permanentes à un préfixe retraité et utilise le prefix caching — les fichiers de règles de Cursor, les instructions de Copilot, et similaires. Les noms diffèrent ; le calcul, non. Tout agent facturé au token qui relit sa couche d'instructions à chaque tour récompense un fichier petit et stable et punit un fichier tentaculaire et mouvant. Voir agentic coding pour comprendre pourquoi la relecture par tour est structurelle plutôt qu'accidentelle.Voir aussi :
- Comment réduire l'usage de tokens de Claude Code — le pilier dont cet article est issu.
- Le context engineering pour les agents de codage IA — fournir le bon contexte par tour, pas tout le contexte.
- Prompt caching — le mécanisme qui rend un CLAUDE.md stable bon marché.
- Coûts en tokens des agents de codage IA — le calcul de prix derrière les exemples ci-dessus.
Classé n°1 au Token-Harness Optimizer Leaderboard.
Tokenade est classé n°1 au Token-Harness Optimizer Leaderboard — un benchmark de bout en bout des optimiseurs de tokens, mesuré sur de vraies sessions de code. Installez-le une fois, il agit sur chaque prompt. Compatible avec Claude Code, Cursor, Codex, Copilot et plus.