Titre original : How Anthropic Engineers Actually Save Tokens
Auteur original : Nate Herk
Traduction : Peggy, BlockBeats

Préface de l'éditeur : Beaucoup de personnes constatent en utilisant Claude Code que la consommation de tokens est trop rapide, et qu'il est facile de dépasser la limite lors de longues sessions. 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 continuellement le contexte déjà traité.

L'essentiel de cet article est de partager comment économiser des tokens via un mécanisme de cache. En une semaine, l'auteur a réutilisé plus de 300 millions de tokens grâce au cache, avec un pic journalier de 91 millions. Étant donné que le coût pour stocker un token en cache est seulement 10 % de celui d’un token d’entrée normal, 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 longues sessions de 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 prompt caching 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 prompt cache, car cela impacte non seulement le quota utilisateur, mais aussi le coût de 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 habitudes clés : 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 pensée d’ingénieur pour utiliser Claude Code : considérer le contexte comme un actif à gérer, faire perdurer le cache, et réduire les calculs redondants dans les longues sessions.

Voici le texte original :

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

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

Mais une fois que j’ai compris ce qu’était le cache, et comment éviter de le « couper », mes sessions peuvent durer plus longtemps avec le même quota. Voici donc un guide d’introduction au prompt caching de Claude Code, basé sur le principe 80/20, sans entrer dans les détails de l’API.

TL;DR

Le coût pour stocker un token en cache est seulement 10 % de celui d’un token d’entrée classique. 91 millions de tokens en cache coûtent en réalité environ 9 millions de tokens.

La durée de vie du cache (TTL) pour l’abonnement Claude Code est d’1 heure ; par défaut, l’API a 5 minutes ; le sous-agent (Sub-agent) a 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 normal.

Donc, lorsque mon tableau de bord indique que 91 millions de tokens ont été mis en cache en une journée, la facturation réelle correspond à environ 9 millions de tokens traités. C’est aussi pour cela qu’avec le cache, l’utilisation prolongée de Claude Code semble presque « gratuite ».

Deux chiffres dans le tableau de bord méritent une attention particulière :

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

Si votre chiffre de Cache read est élevé, cela indique une utilisation efficace du cache ; s’il est faible, cela 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 prompt cache, 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 devient plus rapide, le coût chez 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.

Ainsi, les deux parties ont des intérêts alignés : Anthropic souhaite que votre taux de hit soit élevé, et vous aussi. Les habitudes qui peuvent réellement freiner cette efficacité sont souvent insignifiantes en apparence, mais peuvent réinitialiser le cache discrètement.

Comment le cache se développe-t-il à chaque tour de dialogue ?

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

Inutile d’entrer dans des détails techniques complexes, il suffit de comprendre : tant que le contenu avant une certaine position correspond exactement au contenu déjà en cache, Claude peut réutiliser cette partie du cache de tokens.

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

Selon la documentation de Claude Code, une nouvelle session fonctionne généralement ainsi :

Premier tour : aucun cache n’est encore présent. Les instructions système, le contexte du projet (comme CLAUDE.md, la mémoire, les règles), et votre premier message sont retraités et mis en cache.

Deuxième tour : tout le contenu de la première interaction est maintenant en cache. Claude ne traite que votre nouvelle réponse et le message suivant. Le coût de cette étape est beaucoup plus faible.

Troisième tour : même principe. La conversation précédente reste en cache, seul le dernier échange doit être retraité.

Le cache lui-même se divise en trois couches :

Extrait de l’article de Thariq sur X :

Couche système (System layer) : instructions de base, définition des 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. Elle est spécifique à chaque 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 depuis le début. C’est la opération la plus « coûteuse ». Imaginez : vous en êtes à la 16e message, et soudain vous modifiez l’instruction système ou faites une pause d’une heure, alors tous les tokens depuis le premier message doivent être retraités.

Confusion entre 1 heure et 5 minutes

C’est la confusion la plus courante.

Claude Code, version abonnement : TTL par défaut d’1 heure.

Claude API : TTL par défaut de 5 minutes. Vous pouvez payer plus pour l’étendre à 1 heure.
Tout plan confondu : le sous-agent (Sub-agent) a toujours 5 minutes.

Claude.ai en chat web : aucune documentation officielle claire. Peut-être identique à la version abonnement, mais je n’ai pas encore vérifié.

Il y a quelques mois, beaucoup se plaignaient que leur quota Claude était consommé trop vite. Certains pensaient que Anthropic avait discrètement réduit le TTL de 1 heure à 5 minutes sans prévenir. Mais ce n’est pas le cas : le 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 que ces deux produits sont totalement différents, ce qui a créé beaucoup de confusion.

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

Trois habitudes pour couvrir 95 % des utilisateurs

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

Ne pas laisser la session inactive trop longtemps

Si vous restez inactif plus d’une heure, le cache de votre session expire généralement. La prochaine réponse reconstruira le cache. Dans ce cas, il vaut mieux faire une transition claire et commencer une nouvelle session, ce qui coûte souvent moins cher.

Reprendre une tâche en recommençant

/compact ou /clear détruisent le cache, il vaut donc mieux utiliser ces commandes pour faire une vraie réinitialisation.

J’ai moi-même développé une technique de passation de session, pour remplacer /compact. Elle consiste à résumer ce que nous avons fait, les décisions en suspens, les fichiers importants, et où continuer. Ensuite, j’exécute /clear, en collant ce résumé, et je peux continuer comme si rien n’avait été interrompu.

Le commandement /compact peut parfois être lent. La technique de passation de session, elle, prend généralement moins d’une minute.

Pour les gros documents, privilégiez leur intégration 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 directement.

Quels éléments peuvent discrètement casser le cache ?

Plusieurs actions peuvent réinitialiser le cache sans avertissement.

Changer de modèle : le cache dépend de la correspondance de 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 » : cette configuration utilise Opus en phase de planification, puis Sonnet en phase d’exécution. Je l’avais recommandée 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, et donc à reconstruire le cache. Sur le long terme, cela peut aider à prolonger le quota, mais il faut connaître ce qui se passe en coulisses.

Modifier le fichier CLAUDE.md en cours de session est possible : cette modification ne prend effet qu’au prochain redémarrage. Le cache en cours n’est pas affecté.

Mon tableau de bord de tokens gratuits

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

https://github.com/nateherkai/token-dashboard

C’est un dépôt GitHub très simple. Vous donnez le lien à Claude Code, qui déploie localement sur localhost, 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 suit que les tokens sur votre machine locale. Si vous passez d’un PC à un portable, les chiffres ne seront pas identiques. Chaque appareil a sa propre vue.

Résumé

Le prompt caching est un sujet très approfondi. L’article de Thariq est plus complet, si vous souhaitez voir la vue d’ensemble, 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 : stocker en cache des tokens 10 fois moins cher, TTL d’1 heure pour Claude Code, changer de modèle pour éviter de casser le cache, faire une passation claire entre tâches, plutôt que de laisser un vieux dialogue « expirer » et continuer dessus.

[ lien vers l’article original ]

Cliquez pour découvrir les opportunités chez律动BlockBeats

Rejoignez la communauté officielle de律动BlockBeats :
Telegram abonnement : https://t.me/theblockbeats
Telegram groupe : https://t.me/BlockBeats_App
Twitter officiel : https://twitter.com/BlockBeatsAsia