Une semaine d'économie de 300 millions de tokens, Guide de cache du code Claude des ingénieurs d'Anthropic

Titre original : Comment les ingénieurs d'Anthropic économisent réellement des tokens
Auteur original : Nate Herk
Traduit par : Peggy, BlockBeats

Auteur original : BlockBeats

Source originale :

Reproduit : Mars Finance

Préface : Beaucoup de personnes constatent que lorsqu'elles utilisent Claude Code, la consommation de tokens est très rapide, et les longues sessions consomment facilement leur quota. Mais du point de vue des ingénieurs d'Anthropic, ce qui influence réellement le coût, ce n’est pas tant la quantité de code que vous écrivez, mais si le système réutilise en continu le contexte déjà traité.

L’essentiel de cet article est de partager comment économiser des tokens via un mécanisme de cache. L’auteur a réutilisé plus de 300 millions de tokens en une semaine grâce au cache, avec un pic journalier de 91 millions. Étant donné que le coût pour stocker des tokens en cache est seulement 10 % de celui des tokens d’entrée classiques, cela signifie que 91 millions de tokens en cache coûtent en réalité environ 9 millions de tokens classiques. La longévité accrue des sessions avec Claude Code n’est pas due à un modèle gratuit, mais à la réutilisation efficace de contextes répétés.

L’astuce clé du cache de prompt est de « ne pas interrompre le cache ». Claude Code met en cache en couches : les instructions système, la définition des outils, le fichier CLAUDE.md, les règles du projet et l’historique des dialogues ; tant que le préfixe de la requête suivante reste identique, Claude peut directement lire le cache sans retraiter tout le contexte. Chez Anthropic, ils surveillent aussi le taux de réutilisation du cache de prompt, car cela impacte non seulement le quota utilisateur, mais aussi le coût du service et l’efficacité opérationnelle.

Pour l’utilisateur lambda, il n’est pas nécessaire de comprendre tous les détails techniques, mais il faut adopter quelques bonnes habitudes : ne pas laisser une session inactive plus d’une heure ; faire une passation de session lors du changement de tâche ; éviter de changer fréquemment de modèle ; pour de gros documents, privilégier leur intégration dans Projects plutôt que de les coller à répétition dans la conversation.

Cet article ne se limite pas à une technique d’économie de tokens, mais propose une approche plus proche de la mentalité d’ingénieur pour utiliser Claude Code : considérer le contexte comme un actif à gérer, faire perdurer le cache, et limiter les calculs redondants lors de longues sessions.

Voici la version originale :

Cette semaine, j’ai économisé 300 millions de tokens, avec 91 millions en une seule journée, plus de 300 millions en une semaine.

Je n’ai modifié aucun paramètre. C’est simplement le cache de prompt qui fonctionne normalement en arrière-plan.

Mais lorsque j’ai compris ce qu’était réellement le cache, et comment éviter de « briser » le cache, j’ai pu prolonger la durée de mes sessions tout en restant dans le même quota. Donc, voici un guide d’introduction 80/20 au cache de prompt de Claude Code, sans entrer dans les détails techniques de l’API.

TL;DR

Le coût pour stocker des tokens en cache n’est que 10 % de celui des tokens d’entrée classiques. 91 millions de tokens en cache, coût réel d’environ 9 millions de tokens.

La durée de vie (TTL) du cache pour la version abonnement de Claude Code est d’1 heure ; par défaut, l’API a une TTL de 5 minutes ; le sous-agent (Sub-agent) est toujours à 5 minutes.

Le cache se divise en trois couches : couche système, couche projet, couche conversation.

Changer de modèle en cours de session détruit le cache, y compris en mode « opus plan ».

Comment le cache est-il facturé ?

Chaque token mis en cache coûte 10 % de celui d’un token d’entrée.

Ainsi, lorsque mon tableau de bord indique que 91 millions de tokens ont été utilisés en cache un jour donné, la facturation réelle correspond à environ 9 millions de tokens traités. C’est pour cela qu’avec le cache, l’utilisation prolongée de Claude Code donne l’impression que la conversation est « presque gratuite ».

Deux chiffres clés dans le tableau de bord :

• Cache create : coût ponctuel lors de l’écriture dans le cache. Il commence à jouer un rôle lors de la prochaine interaction.
• Cache read : tokens réutilisés depuis le cache par Claude, comme votre CLAUDE.md, la définition des outils, ou les messages précédents. Leur coût est 10 fois inférieur à celui du traitement en entrée.

Un taux élevé de Cache read indique une utilisation efficace du cache ; un taux faible signifie que vous payez plusieurs fois pour le même contexte.

Thariq d’Anthropic a dit une phrase qui m’a marqué : « Nous surveillons en fait le taux de hit du cache de prompt, et si ce taux devient trop faible, une alerte est déclenchée, voire un incident de niveau SEV. »

Il a aussi écrit un excellent article sur X. Quand le taux de hit est élevé, quatre choses se produisent simultanément : Claude Code se sent plus rapide, le coût du service d’Anthropic diminue, votre quota d’abonnement dure plus longtemps, et les longues sessions de codage deviennent plus réalistes.

Mais si le taux de hit est faible, tout le monde en pâtit.

En réalité, l’incitation est alignée : Anthropic veut que votre taux de hit soit élevé, et vous aussi. Le seul vrai frein, ce sont quelques habitudes apparemment anodines mais qui, en réalité, réinitialisent silencieusement le cache.

Comment le cache se construit-il à chaque tour de conversation ?

Le cache repose sur la correspondance de préfixe, c’est-à-dire le « prefix matching ».

Pas besoin d’entrer dans tous les détails techniques, il suffit de comprendre : tant que le contenu avant une position donnée correspond exactement à ce qui est déjà en cache, Claude peut réutiliser cette partie du cache.

Une nouvelle session se déroule généralement ainsi :

Selon la documentation de Claude Code, une nouvelle session fonctionne ainsi :

• Premier tour : pas de cache. Les instructions système, le contexte du projet (CLAUDE.md, mémoire, règles), et le premier message sont retraités et stockés dans le cache.
• Deuxième tour : tout le contenu de la première étape est déjà en cache. Claude ne traite que la nouvelle réponse et le message suivant. Le coût est alors beaucoup plus faible.
• Troisième tour : même principe. La conversation précédente reste en cache, seul le dernier échange est retraité.

Le cache se divise en trois couches :

D’après Thariq dans son article X :

• Couche système (System layer) : instructions de base, définitions d’outils (read, write, bash, grep, glob) et style de sortie. C’est la couche de cache globale.
• Couche projet (Project layer) : CLAUDE.md, mémoire, règles du projet. Cache spécifique au projet.
• Couche conversation (Conversation) : réponses et messages, qui s’accumulent à chaque tour.

Si, en cours de session, la couche système ou la couche projet change, tout doit être re-cache. C’est la opération la plus coûteuse. Imaginez : après 16 messages, si vous modifiez la prompt système ou faites une pause d’une heure, tout le contexte depuis le premier message doit être retraité.

Confusion entre 1 heure et 5 minutes

C’est la confusion la plus courante.

Claude Code abonnement : TTL par défaut = 1 heure.

API Claude : TTL par défaut = 5 minutes. Vous pouvez payer plus pour l’étendre à 1 heure.
Sous-agent (Sub-agent) : toujours 5 minutes.

Chat sur le site Claude.ai : pas de documentation officielle. Peut-être comme la version abonnement, mais je n’ai pas confirmé.

Il y a quelques mois, beaucoup se plaignaient que leur quota Claude se consumait trop vite. Certains pensaient qu’Anthropic avait discrètement réduit la TTL de 1 heure à 5 minutes sans prévenir. Mais ce n’est pas le cas : la TTL de Claude Code reste à 1 heure.

Le problème vient du fait que la documentation de Claude Code et celle de l’API sont séparées, et qu’elles désignent deux choses différentes, ce qui cause beaucoup de confusion.

Si vous faites beaucoup de workflows avec le Sub-agent ou utilisez directement l’API, la valeur de 5 minutes est importante. Mais pour 95 % des utilisateurs de Claude Code, l’essentiel est la fenêtre de 1 heure.

Trois habitudes pour couvrir 95 % des besoins

Voici ce que je trouve vraiment utile dans la pratique quotidienne :

Ne pas laisser une session inactive trop longtemps

Si vous restez inactif plus d’une heure, le cache expire généralement. La prochaine réponse reconstruira le cache. Plutôt que de continuer une session « refroidie », il vaut mieux faire une transition claire, puis démarrer une nouvelle session, ce qui coûte souvent moins cher.

Lors du changement de tâche, recommencer proprement

/compact ou /clear détruisent le cache. Mieux vaut profiter de ce moment pour faire une vraie réinitialisation.

J’ai créé une compétence de passation de session, pour remplacer /compact. Elle résume ce qu’on a fait, les décisions en suspens, les fichiers importants, et indique où continuer. Ensuite, j’exécute /clear et colle ce résumé, pour continuer comme si rien n’avait été interrompu.

Le commandement /compact peut parfois être lent. La compétence de passation, elle, se termine en moins d’une minute.

Dans la conversation Claude, pour de gros documents, il vaut mieux les mettre dans Projects

Le mécanisme de cache sur Claude.ai n’est pas très documenté officiellement, mais il semble que Projects utilise une optimisation différente des conversations classiques. Donc, si vous collez de gros documents, il vaut mieux les mettre dans Projects plutôt que dans la conversation.

Quels actions peuvent silencieusement casser le cache ?

Plusieurs actions peuvent, sans avertissement, tout réinitialiser :

Changer de modèle : le cache dépend du préfixe, et chaque modèle a son propre cache. En changeant de modèle, la prochaine requête ne trouvera aucun cache correspondant, et tout sera retraité. Mode « opus plan » : ce mode utilise Opus en phase de planification, puis Sonnet en phase d’exécution. Je l’avais recommandé dans des vidéos d’optimisation de tokens, et c’est pour une bonne raison. Mais il faut comprendre que chaque changement de plan revient à changer de modèle, donc à reconstruire le cache. Sur le long terme, cela peut aider à prolonger le quota, mais il faut connaître le fonctionnement sous-jacent. Modifier CLAUDE.md en cours de session : cela ne prend pas effet immédiatement, il faut attendre le prochain redémarrage. Le cache en cours n’est pas affecté.

Mon tableau de bord Token gratuit

Les captures d’écran précédentes proviennent d’un tableau de bord Token.

C’est un simple dépôt GitHub. Vous donnez le lien à Claude Code, qui déploie localement, et il lit toutes vos sessions passées, sans repartir de zéro. Vous pouvez voir chaque jour le nombre d’inputs, outputs, cache create et cache read.

Attention cependant : ce tableau de bord ne mesure que les tokens sur votre machine locale. Si vous changez d’ordinateur, les chiffres ne seront pas identiques. Chaque appareil a sa propre vue.

Résumé

Le cache de prompt est un sujet très riche. L’article de Thariq est plus complet, si vous souhaitez une vision globale, il vaut la peine de le lire.

Mais vous n’avez pas besoin de tout comprendre pour en bénéficier. Il suffit de maîtriser l’essentiel 80/20 : le cache de tokens coûte 10 fois moins cher que les tokens classiques ; la TTL de Claude Code est d’1 heure ; changer de modèle détruit le cache ; faire une passation claire entre tâches est souvent plus rentable que de laisser une session « expirer » puis de la réutiliser à la hâte.