L'équipe Claude Code déclare l'état d'urgence quand cette métrique chute
L'équipe derrière Claude Code vient de révéler — publiquement, tranquillement, dans un tweet — que le prompt caching est l'unique infrastructure qui rend leur produit viable. Pas une optimisation sympa. Pas un hack pour économiser. Le mur porteur.
TL;DR : À chaque message envoyé à Claude (API ou Claude Code), le système vérifie s'il a déjà traité le début de votre prompt. Si oui : 10x moins cher, 85% plus rapide. Si non : prix plein, attente complète. L'équipe Claude Code surveille cette métrique comme un rythme cardiaque et déclare des incidents quand elle chute. La plupart des devs cassent leur cache sans le savoir. Cet article explique ce qu'est le prompt caching, pourquoi c'est crucial, et les erreurs qui vous coûtent de l'argent en ce moment même.
Leur devise ? "Cache Rules Everything Around Me."
Si vous avez grandi avec Wu-Tang, vous reconnaissez la référence. Sinon — CREAM parlait de fric qui dirige tout. La version Claude Code parle de tenseurs KV qui dirigent tout. Même énergie, devise différente. Et comme l'original, si vous ignorez le message, vous allez le payer cher.
La plupart des devs à qui je parle ne savent pas ce qu'est le prompt caching. Ils ne savent définitivement pas qu'ils en bénéficient à chaque ouverture de session Claude Code. Et ils ne savent absolument pas que leur façon de structurer leurs prompts peut soit toucher le cache, soit le rater — leur coûtant vitesse, argent, ou les deux.
Voici la version simplifiée.
Et oui, vous vous y prenez probablement mal.
0,045$ vs 0,005$ — même requête, même modèle, même résultat
Je vais commencer par le chiffre qui m'a fait vraiment m'intéresser à ce sujet.
Un de mes projets Convex a un assistant IA — prompt système de ~6 000 tokens, 12 définitions d'outils (auth Clerk, requêtes Supabase, quelques actions custom), conversations typiques de 15-20 échanges. Du standard. Rien d'exotique.
J'ai tiré mon usage API après une semaine et fait le calcul sur une conversation de 20 échanges :
- Sans cache : chaque requête en fin de conversation traite ~15 000 tokens de contexte au prix plein. ~0,045$ par requête.
- Avec cache : seuls les derniers ~500 tokens (nouveau message + réponse précédente) nécessitent un calcul frais. Tout le reste touche le cache. ~0,005$ par requête.
Neuf. Fois. Moins. Cher.
Multipliez par 1 000 conversations par jour et vous regardez 1 350$/mois vs 150$/mois. Je n'ai pas découvert le prompt caching via un article de blog ou une conférence. Je l'ai découvert en fixant un tableau de bord Stripe, me demandant pourquoi mon environnement de test brûlait des crédits comme un gamin avec sa carte cadeau d'anniversaire chez GameStop. Bref — le point c'est que je me serais épargné deux semaines de confusion si quelqu'un me l'avait expliqué comme je vais vous l'expliquer.
Ce qu'est vraiment le prompt caching (version Wu-Tang)
À chaque appel de l'API Claude — ou chaque fois que Claude Code exécute une action sous le capot — un prompt s'assemble. Ce prompt a quatre couches :
- Le prompt système (vos instructions, personnalité, contraintes)
- Définitions d'outils (toutes les fonctions que Claude peut appeler)
- Historique de conversation (messages précédents de la session)
- Le nouveau message utilisateur (ce que vous venez de taper)
Sans cache, Claude retraite chaque token depuis zéro. À chaque fois. Votre prompt système de 8 000 tokens ? Retraité. Vos 15 définitions d'outils ? Retraitées. Les 40 messages précédents de la conversation ? Tout, depuis zéro — comme un poisson rouge qui lit le même livre pour la première fois, éternellement.
Le prompt caching stocke les tenseurs Key-Value calculés (les maths lourdes que fait le modèle pendant la phase "prefill") pour un préfixe exact de votre prompt. Requête suivante avec le même préfixe ? On zappe les maths, on réutilise le résultat stocké.
Le cache vit 5 minutes par défaut. Les nouveaux modèles Claude 4.5 supportent un TTL d'1 heure à 2x le coût d'écriture. Et la correspondance est exacte — un caractère différent dans votre préfixe et tout le cache s'invalide. C'est comme un scanner d'empreintes qui vérifierait aussi votre humeur.
CREAM. Cache Rules Everything Around Me. Chaque requête que vous envoyez soit touche le cache et paie 0,1x le prix d'entrée, soit le rate et paie plein pot. Il n'y a pas d'entre-deux.
Les 3 erreurs qui brûlent votre argent
C'est la partie où j'arrête d'être sympa. Un papier de recherche appelé "Don't Break the Cache" a testé les stratégies de cache sur OpenAI, Anthropic et Google avec 500+ sessions d'agents. Combiné à ce que l'équipe Claude Code a partagé, le pattern est clair : la plupart des devs cassent leur cache des trois mêmes façons.
Erreur #1 : Injecter de la merde dynamique dans votre prompt système.
Timestamps. IDs de requête. Données spécifiques utilisateur. Tokens de session. À chaque fois que vous fourrez quelque chose de dynamique dans vos instructions système, tout le préfixe devient unique. Cache raté. Prix plein. À chaque putain de fois.
Je l'ai fait. J'avais un "Heure actuelle : ${new Date().toISOString()}" dans mon prompt système pour le "contexte." Ça m'a coûté probablement 40$ en appels API inutiles avant que je réalise. Le fix a pris 8 secondes — déplacer le timestamp dans le message utilisateur à la place.
{
"system": [
{
"type": "text",
"text": "Tu es un assistant de revue de code pour une app Next.js + Convex...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{"role": "user", "content": "Heure actuelle : 2026-02-19T14:30:00Z\n\nReview cette fonction..."}
]
}
Le tag cache_control dit à Anthropic : "cache tout jusqu'ici." Prompt système statique = caché. Timestamp dynamique dans le message utilisateur = ne casse pas le préfixe. Une restructuration. 90% d'économies sur ce chunk.
Si vous voulez le framework complet pour structurer des prompts système qui non seulement cachent bien mais produisent vraiment une sortie fiable, j'ai écrit sur les Prompt Contracts — même philosophie, angle différent.
Erreur #2 : Réordonner les outils entre requêtes.
Anthropic traite le préfixe cachable dans un ordre spécifique : outils → système → messages. Si votre code assemble les définitions d'outils depuis une Map ou un Set non ordonné, l'ordre peut se mélanger entre requêtes. Ordre différent = préfixe différent = cache raté. Vous n'avez changé aucun outil. Vous n'avez rien ajouté ni retiré. Vous avez juste laissé les bizarreries d'ordonnancement d'objets JavaScript vous coûter de l'argent.
Fix : triez vos outils alphabétiquement ou par index fixe avant envoi. Mortellement ennuyeux. Extrêmement profitable. Et si vous vous demandez si vous avez même besoin de toutes ces définitions d'outils — les CLIs pourraient être un meilleur pari que les MCPs. Moins d'outils = préfixe plus petit = cache hit plus facile.
Erreur #3 : Ne pas utiliser de breakpoints du tout (spécifique Anthropic).
Contrairement à OpenAI (qui cache automatiquement pour les prompts de plus de 1 024 tokens), Anthropic exige que vous marquiez explicitement quoi cacher avec des breakpoints cache_control. Si vous ne les ajoutez pas, rien n'est caché. Vous payez plein prix et vous demandez pourquoi Claude semble lent.
Pour les conversations multi-tours, vous avez jusqu'à 4 breakpoints total. La recherche a trouvé la répartition optimale : 1 sur le prompt système, 3 sur les messages utilisateur récents. Ceci cache à la fois vos instructions statiques et votre historique de conversation récent. Sans les breakpoints de messages utilisateur, l'usage intensif d'outils entre tours crée des gaps non cachés qui continuent de grandir — comme une fuite mémoire mais pour votre portefeuille.
Pourquoi vos sessions Claude Code semblent rapides (jusqu'à ce qu'elles ne le soient plus)
Petit détour pour la foule des abonnements. Si vous êtes sur Claude Code (pas l'API), vous ne configurez rien de tout ça manuellement. Le harness gère l'optimisation de cache — c'est littéralement ce sur quoi l'équipe passe son temps d'ingénierie, et apparemment déclare des urgences.
Mais comprendre comment ça marche explique quelques trucs que vous avez probablement remarqués :
Le premier message dans une nouvelle session est toujours plus lent. C'est l'écriture de cache. Le prompt système, votre CLAUDE.md, toutes les définitions d'outils — calculés et stockés pour la première fois. Chaque message après bénéficie du cache. Le démarrage à froid est l'échauffement.
Changer de projet en milieu de session semble poussif. Contexte de projet différent = prompt système différent = cache raté. Le système doit construire un nouveau cache depuis zéro. Pas un bug. Juste de la physique.
Les longues sessions semblent généralement rapides. L'historique de conversation continue de grandir mais touche surtout le cache. Le tour 30 réutilise le préfixe caché des tours 1-29 et ne traite que le nouveau truc. C'est pourquoi l'équipe Claude Code a construit toute leur architecture autour de ça — sans cache, votre 50e message traiterait 50x plus de tokens que votre premier. Le produit serait mort au message 15. Comme un thread Slack qui chargerait chaque message précédent depuis zéro à chaque fois que quelqu'un tape "ça marche" — mais je digresse.
Et parfois ça ralentit au hasard. Si l'équipe ship un changement qui modifie accidentellement l'ordre d'assemblage des prompts, ou si une mise à jour interne décale une définition d'outil, le cache de chaque utilisateur casse simultanément. C'est le SEV. C'est le pager qui sonne. "Cache Rules Everything Around Me" n'est pas une devise mignonne. C'est un manuel d'opérations.
Ce que ça signifie vraiment pour vous
Si vous buildez sur l'API Claude : allez vérifier vos prompts système maintenant. S'il y a quoi que ce soit de dynamique dedans — une date, un ID utilisateur, une graine aléatoire, n'importe quoi qui change entre requêtes — déplacez-le dans le message utilisateur. Ajoutez des breakpoints cache_control. Triez vos outils. Faites-le aujourd'hui. Le ROI est immédiat et embarrassant. J'ai appris ça à mes dépens quand Anthropic a tué mon setup OpenClaw à 200$/mois — une fois que vous rebuildez sur API au lieu d'un abonnement, chaque dollar d'optimisation compte.
Si vous utilisez Claude Code sur abonnement : vous n'avez rien à faire. Mais maintenant vous comprenez pourquoi l'équipe traite le prompt caching comme l'alimentation en oxygène d'une station spatiale. Et la prochaine fois que votre premier message prend 6 secondes et votre dixième message prend 1,5, vous saurez exactement ce qui s'est passé.
Dans tous les cas, CREAM. Le cache dirige tout autour de vous, que vous le sachiez ou non. La seule question c'est si vous êtes du côté pas cher ou du côté cher.
Les devs qui comprennent leur infra shippent moins cher. Ceux qui ne comprennent pas subventionnent les rate limits de tout le monde.
À suivre : Anthropic vient de tuer les harnesses tiers utilisant les abonnements Claude. Mon setup OpenClaw à 200$/mois est mort du jour au lendemain. J'ai tout reconstruit pour 15$ — et le prompt caching est la moitié de la raison pour laquelle ça marche.
Comment l'équipe Claude Code surveille ses métriques de prompt caching pour éviter des pertes massives ? Découvrez les coulisses d'une infrastructure critique en production.