Cache des prompts des agents de code : coûts et limites

Chaque étape d'une session d'agent est une nouvelle requête API : vos messages comme les résultats d'outils que l'agent renvoie. Le modèle ne garde rien entre deux requêtes. L'agent retransmet donc le prompt système, les outils, les instructions du projet, toute la conversation et les nouveaux éléments. Presque tout correspond à la requête précédente. Le cache permet au fournisseur de ne pas le retraiter entièrement.

Claude Code gère le cache pour vous. Sur l'API, un champ cache_control de premier niveau active le cache automatique. Les modèles OpenAI utilisés par Codex CLI suivent eux aussi une règle de préfixe, mais avec leurs tarifs et leurs durées. Les chiffres ci-dessous concernent Claude.

Un préfixe exact, dans un ordre fixe

Le cache compare le début de chaque requête, son préfixe, à ce qu'il a traité récemment. La correspondance doit être exacte : un seul caractère modifié invalide tout ce qui suit. Il n'y a pas de cache indépendant pour chaque fichier ou section.

L'ordre est fixe : définitions d'outils, prompt système, puis messages. Un changement à un niveau invalide ce niveau et tous les suivants. Modifier un message laisse les outils et le prompt système en cache ; modifier un outil invalide tout.

Claude Code place les éléments les plus stables en tête : ses instructions et outils, puis votre contexte de projet (CLAUDE.md, mémoire, règles), enfin la conversation. Sur un tour ordinaire, la requête précédente entière constitue le préfixe et seul le dernier échange est nouveau.

Prix des écritures et lectures du cache

Le cache modifie le prix de l'entrée, pas celui de la réponse. En septembre 2026, Anthropic facture l'écriture à 1,25 fois le prix de base pour cinq minutes et à deux fois pour une heure. Une lecture coûte un dixième, sauf sur Claude Fable 5.1 (0,025 fois) et Claude Opus 5.5 (0,05 fois). Ce qui suit le dernier point de cache est facturé comme entrée ordinaire.

Prenons 100 000 tokens de contexte sur Claude Sonnet 5, au prix public de 2 $ par million de tokens d'entrée en septembre 2026. Une lecture du cache coûte 0,02 $ par requête, contre 0,20 $ sans cache. Après un raté, une nouvelle écriture coûte 0,25 $ pour cinq minutes ou 0,40 $ pour une heure. Un raté coûte davantage qu'une requête sans cache, puisque l'écriture est majorée.

Au tarif de cinq minutes, réécrire coûte 12,5 fois une lecture sur la plupart des modèles, 25 fois sur Opus 5.5 et 50 fois sur Fable 5.1. Plus la lecture est bon marché, plus l'écart est grand. Une écriture de cinq minutes est rentabilisée dès la première lecture ; il en faut deux avec une heure.

Cinq minutes ou une heure

La durée de vie, ou TTL, est le temps pendant lequel le préfixe survit sans être utilisé. Chaque lecture relance gratuitement le délai. Celui-ci commence au début de la requête, pas à la fin de la réponse : si une réponse met quatre minutes à arriver, il reste environ une minute pour réutiliser un cache de cinq minutes.

En septembre 2026, Claude Code donne une heure à la conversation principale sur un abonnement Claude dans l'usage inclus, et cinq minutes avec une clé API, un fournisseur cloud ou des crédits d'usage. Les sous-agents reçoivent cinq minutes par défaut dans tous les cas.

Pour choisir la durée du fil principal, définissez promptCacheTtl dans les réglages ou CLAUDE_CODE_PROMPT_CACHE_TTL dans l'environnement à 5m ou 1h (Claude Code v2.1.242 ou plus). L'heure est utile pour des pauses de cinq à soixante minutes, par exemple une réunion, une revue ou une longue compilation. Si vos requêtes sont toujours espacées de moins de cinq minutes, elle ne fait qu'augmenter le prix de chaque écriture.

$claude -p "hello" --output-format json

Ce qui casse le cache sans avertissement

Un raté ne produit pas d'erreur : le tour ralentit et le rapport d'usage affiche une grosse écriture à la place d'une lecture. Causes fréquentes dans un agent de code :

• →Changer de modèle. Chacun possède son cache : /model pendant la tâche relit l'historique sans remise. Il en va de même pour un skill qui impose un autre modèle ou le mode plan opusplan, qui alterne Opus et Sonnet.
• →Changer l'effort. Sur la plupart des modèles, chaque niveau dispose de son cache. En septembre 2026, Opus 5.5 et Fable 5.1 le conservent lors du changement, avec une clé API ou un abonnement Claude.
• →Modifier les outils. Leurs définitions viennent en premier, donc toute modification peut invalider le préfixe. Claude Code diffère les outils MCP par défaut, ce qui laisse les changements de serveurs hors de cette partie. Avec un chargement immédiat, par exemple derrière une passerelle ANTHROPIC_BASE_URL, un serveur qui s'arrête puis se reconnecte casse le cache.
• →Faire varier le début du prompt. Un horodatage dans le prompt système réécrit tout ce qui suit à chaque requête. Une mise à jour de Claude Code change souvent ce prompt ; la première session après mise à jour démarre donc à froid.
• →Dépasser la durée de vie : cinq minutes par défaut avec une clé API, une heure avec un abonnement.

Pourquoi le premier tour après une pause coûte plus

Un raté se paie une fois, à la requête suivante : tout le préfixe est retraité et réécrit au tarif majoré. Les requêtes suivantes le relisent de nouveau à prix réduit. C'est pourquoi le premier message après une pause peut être lent et cher, même s'il ne contient qu'une ligne.

Le compactage crée volontairement un nouveau préfixe. Tant que le cache est actif, la requête de résumé relit l'historique à tarif réduit. Après une longue pause, elle retraite toute la conversation sans cache : une session que vous venez de reprendre est le moment le plus coûteux pour compacter.

Les habitudes qui suivent : choisissez modèle et effort au début, terminez une tâche avant une pause, et utilisez /clear quand le sujet change plutôt que ressusciter un long fil froid. Pour abandonner une fausse piste, /rewind revient à un préfixe déjà en cache. Sur Pro et Max, Claude Code propose de reprendre une grande session à partir d'un résumé après une longue pause.

Lire le taux de réussite du cache

L'API rapporte trois comptes d'entrée par réponse : cache_read_input_tokens pour les lectures, cache_creation_input_tokens pour les écritures, et input_tokens pour ce qui suit le dernier point de cache. Ce dernier paraît donc faible quand une session utilise bien le cache. Le total est la somme des trois.

Le taux de réussite est le nombre de lectures divisé par ce total. Dans une longue session encore active, la majeure partie de chaque requête devrait être relue. Un faible taux est normal dans une session courte, où la première écriture pèse lourd. Dans une session longue, de grosses écritures à chaque tour signalent une cause de la liste précédente.

$/usage

Depuis v2.1.260, cette ligne nomme aussi la cause probable du dernier raté lorsqu'elle peut l'établir, par exemple des définitions d'outils modifiées. Elle ne couvre que la conversation principale : un sous-agent possède son propre prompt et ses propres outils. Sur l'API, la page Usage de la Console trace la part d'entrée relue ; les diagnostics de cache, en bêta en septembre 2026, indiquent où deux requêtes successives divergent.

Abonnement ou API : qui paie un raté ?

Avec une clé API, un raté coûte de l'argent aux tarifs du tableau et réduit la marge sous la limite de tokens d'entrée par minute. Sur la plupart des modèles Claude, les lectures du cache ne comptent pas dans cette limite, contrairement aux écritures et à l'entrée non mise en cache.

Sur Pro ou Max, aucun token n'est facturé séparément ; le montant en dollars de /usage est une estimation pour l'API. Le raté consomme plutôt les limites du plan. La documentation de Claude Code cite les ratés du cache parmi les raisons pour lesquelles une longue session consomme plus qu'attendu. Sur Pro, Max, Team et Enterprise, /usage les signale dès qu'ils atteignent un dixième de l'usage récent.

Un token en cache reste un token

Même à un dixième du prix, tout le contexte est relu à chaque requête. Comme le rappelle la documentation, une question d'une ligne dans une session ouverte toute la journée mobilise encore l'usage de la conversation entière. Il faut donc garder le début du prompt stable pour préserver le cache et le contexte court pour réduire chaque lecture et chaque raté.

Si vous ne voulez pas surveiller cette taille manuellement, capsul pilote le CLI d'agent auquel vous êtes déjà connecté et envoie ce que la tâche demande sous le budget choisi. Il s'arrête au plafond et indique ce qu'il a omis ; la page du banc d'essai publie les effets mesurés par modèle, avec les vérifications de réponse.