Claude Code : quand l’économie de tokens bute sur l’architecture

Une expérimentation menée sur Claude Code montre que l’optimisation des tokens ne se joue pas seulement dans le prompt, mais dans le contrôle de la boucle agentique elle-même. Sur 27 runs exploitables, le principal plafond venait de l’architecture, pas de la formulation des consignes. Et quand un mécanisme de réduction coupe trop court, il peut même produire un résultat faux sans alerter. Oui, le token grignoté peut coûter plus cher que prévu.

Le cache soulage la facture, pas la charge

Le point de départ de l’analyse tient à un chiffre précis : 98,2 % du volume de tokens observé sur une semaine dans les journaux Claude Code provenait de lectures du cache de prompts. Cela ne voulait pas dire que ces données étaient inutiles. En revanche, cela montrait que la ressource dominante était déjà relue à tarif réduit, sans que le problème de volume disparaisse.

Sur un seul projet de développement, la mesure par rejeu hors ligne a porté sur 16 sessions, 2 618 appels d’API et 3 073 résultats d’outils. Le total atteignait 864 745 067 tokens d’entrée cumulés, soit environ 330 000 par appel. Dans ce corpus, 8 665 429 octets bruts de résultats d’outils ont représenté 1 312 403 581 octets dans le contexte cumulé [à vérifier], soit un rapport d’environ 151. Le cache réduit le prix unitaire, mais il ne supprime pas la circulation des tokens dans la boucle.

Le bon crochet existe, mais il ne couvre pas tout

Claude Code expose bien un point d’interception utile : le hook PostToolUse, associé à updatedToolOutput. Il permet de remplacer le résultat d’un outil avant qu’il soit injecté dans la conversation puis conservé dans l’historique. C’est précisément ce qu’il faut pour externaliser une sortie, conserver une référence courte et limiter l’encombrement immédiat du contexte.

Dans la sonde contrôlée décrite dans les sources, 219 160 octets ont été externalisés. Les références de remplacement ne pesaient que 1 018 octets. L’agent a ensuite récupéré explicitement 4 522 octets, tandis que 213 620 octets ont été écartés du chemin immédiat. La preuve est nette : la substitution avant stockage fonctionne sur Read, Edit et Write, mais seulement sur les sorties d’outils.

Le problème, c’est ce qui échappe à ce crochet. Le hook ne peut pas réécrire un message déjà produit par l’assistant, ni écarter sélectivement un bloc tool_use, ni transformer tout l’historique avant l’envoi suivant. Dans le corpus étudié, les résultats d’outils représentaient 48,9 % du contenu cumulé des transcriptions, les blocs tool_use 15,6 % et le texte de l’assistant avec les prompts 35,5 %. Autrement dit, le levier existe, mais il ne tient pas tout le volant.

Un plafond architectural, pas une simple affaire de prompt

Les données disponibles convergent vers une conclusion simple : le frein principal n’est pas dans le prompt engineering, mais dans l’architecture de la boucle. Sur le workload étudié, le plafond du levier PostToolUse atteint environ 37,9 % des tokens d’entrée. Ce n’est pas une promesse de réduction, seulement la taille maximale du territoire accessible par ce mécanisme.

Une autre mesure éclaire ce plafond. Sur la même machine, les sessions du banc expérimental affichaient environ 3 500 à 5 300 tokens au premier appel, sur 62 observations. Les sessions du projet principal, observées du 28 août au 9 septembre, montaient à environ 35 000 tokens sur 13 observations. L’écart approchait donc 30 000 tokens dès la première requête. Une partie venait des serveurs d’outils déclarés et des extensions chargées ; le reste n’a pas pu être établi précisément [à vérifier].

Cette différence importe, car elle montre que le seul segment vraiment configurable depuis Claude Code sans écrire sa propre boucle reste précisément celui que le hook ne gouverne pas entièrement. Les deux fichiers d’instructions ne représentaient pourtant moins de 2 000 tokens. Le gros du départ se logeait ailleurs.

Quand alléger le contexte casse la tâche

L’expérimentation a aussi produit un échec parlant. Une tâche demandait de recopier intégralement un fichier d’environ 53,7 kilo-octets. Le hook a remplacé le contenu par une référence, l’agent n’a récupéré que 4 096 octets, puis il a écrit la référence elle-même dans le fichier de destination. Résultat final : 339 octets, sans aucune occurrence du contenu attendu.

Le mécanisme de réduction avait bien fonctionné. La tâche, elle, avait été silencieusement corrompue. La cause était claire : la référence indiquait la taille totale de la charge, mais pas la procédure complète de reconstruction. Sans pagination explicite pour couvrir les 54 272 octets, l’agent s’est arrêté trop tôt. Il manque parfois un détail. Et ce détail casse tout.

Ce point change la grille de lecture. Réduire le volume ne suffit pas si l’agent ne sait pas récupérer le contenu au bon moment. Une architecture de gestion du contexte doit donc équilibrer deux variables : ce qu’elle retire de la circulation, et ce qu’elle permet de reconstituer sans perdre la précision fonctionnelle.

Reprendre la main implique de changer d’architecture

Pour dépasser ce plafond, les sources décrivent une autre voie : construire la boucle côté client avec l’API Messages. Dans ce schéma, le client reçoit les blocs tool_use, exécute les outils, fabrique les blocs tool_result et choisit l’historique envoyé à l’appel suivant. Le tableau des messages devient alors gouvernable avant chaque requête.

Anthropic recommande aussi le Tool Runner pour automatiser cette boucle, exécuter les outils et gérer l’état. Mais cette approche n’est pas un hook général de transformation de l’historique. Elle sert justement quand il faut une approbation humaine, une journalisation personnalisée ou une exécution conditionnelle. Dans ce contexte, refuser une charge peut relever d’une décision métier autant que d’un arbitrage technique.

Sur le workload mesuré, une boucle contrôlée par le client rendrait théoriquement gouvernable environ 78 % des tokens d’entrée, selon l’approximation retenue dans les sources. Le prompt système et les définitions d’outils deviennent eux aussi configurables par le client. Cette perspective ne garantit pas une baisse automatique, mais elle redonne un levier sur l’ensemble du contexte reconstituable.

Ce que l’expérience dit d’Anthropic, et ce qu’elle ne dit pas

Les éléments disponibles ne montrent aucune intention d’Anthropic de maintenir artificiellement une consommation élevée. Claude Code propose bien la compaction, l’isolation par sous-agents et d’autres mécanismes de gestion du contexte. L’API Messages offre aussi la possibilité de construire sa propre boucle. Le blocage observé semble donc structurel : l’extension exécutée dans Claude Code ne contrôle pas l’intégralité de l’historique.

Le vrai sujet est là. Pour optimiser l’ensemble du contexte, il ne suffit pas de mieux parler à l’agent. Il faut posséder la boucle qui construit ses messages. C’est moins élégant qu’un bon prompt, mais plus efficace que de demander poliment à une porte de devenir un mur.

Les sources citent enfin un prompt diffusé par le JDN le 14 septembre 2026, intitulé « Pour auditer les skills et MCP à supprimer dans votre agent de code ». Il invite à lire les fichiers, distinguer ce qui est déclaré de ce qui est actif et croiser l’inventaire avec les traces d’usage. Cette logique rejoint l’enseignement principal du dossier : avant de chercher à compresser le contexte, il faut savoir qui injecte quoi, quand, et à quel prix.