Le design de cache qui réduit les coûts API de Claude Code de 90 %

Hier, j’avais du travail urgent en production. En pleine session, mon cache de prompts a lâché. La facture API pour cette seule heure dépassait celle des trois jours précédents réunis.

Le timing était presque comique. Ce même soir, Thariq (l’un des créateurs de Claude Code chez Anthropic) et Lance Martin ont tous les deux publié des articles sur la conception du prompt caching. En lisant leurs explications, j’ai compris que mon cache était fragile par conception, pas par hasard.

Voici ce que j’ai retenu de leurs deux articles, filtré par la douleur en production que je venais de vivre.

Le matching par préfixe : l’ordre prime sur tout

Le prompt caching dans l’API d’Anthropic fonctionne par correspondance depuis le début de la requête, token par token. Dès qu’un seul caractère diffère de la version mise en cache, tout ce qui suit devient un cache miss. Pas de correspondance partielle. Pas de saut en avant.

L’équipe Claude Code traite l’ordre des prompts comme de l’infrastructure. Le system prompt statique passe en premier. Ensuite CLAUDE.md. Puis le contexte de session. Les messages de conversation arrivent en dernier, parce qu’ils changent à chaque tour. Cet ordonnancement garantit que le préfixe stable et coûteux est mis en cache et réutilisé à chaque requête d’une session.

Les tokens en cache coûtent 10 % du prix des tokens d’entrée normaux. Cet écart explique pourquoi un cache cassé donne l’impression d’une multiplication par dix de la facture.

Mon erreur : j’avais intégré un timestamp dans le system prompt. Chaque requête générait un nouveau timestamp, ce qui signifiait que les tout premiers tokens différaient à chaque fois. Rien en aval ne pouvait être mis en cache. Un log de debug au mauvais endroit, et je payais plein tarif sur 100 000 tokens ou plus par requête.

L’équipe Claude Code a également signalé que l’ordre non déterministe des définitions d’outils provoque des cache misses. Si vos outils sont sérialisés dans un ordre différent entre les requêtes, le cache se brise à ce point, même si les outils eux-mêmes n’ont pas changé.

Passer les mises à jour par les messages, pas par le system prompt

Quand le contexte évolue en cours de session (un fichier modifié, l’heure qui tourne, un changement de mode), le réflexe est de mettre à jour le system prompt. C’est une erreur. Toute modification du system prompt invalide l’intégralité du préfixe mis en cache.

Claude Code gère cela en laissant le system prompt intact après la première requête. Le contexte modifié passe dans le prochain message utilisateur, encapsulé dans une balise system-reminder. Le modèle le lit de la même façon, mais le préfixe en cache reste inchangé.

Plan Mode en est un bon exemple. Passer en Plan Mode pourrait impliquer de remplacer des définitions d’outils, ce qui briserait le cache. À la place, Claude Code l’implémente comme un appel d’outil (EnterPlanMode) que le modèle peut invoquer lui-même. L’ensemble des outils ne change jamais. Quand le modèle détecte un problème complexe, il peut entrer en Plan Mode de son propre chef, sans aucune modification du system prompt.

La même logique s’applique au changement de modèle. Changer de modèle en cours de conversation casse entièrement le cache. Claude Code contourne cela en exécutant les différents modèles comme des sous-agents dans des contextes séparés, préservant ainsi le cache de la conversation parente.

Masquer les outils plutôt que les supprimer

Les serveurs MCP peuvent charger des dizaines d’outils. Les inclure tous dans chaque requête est coûteux. Mais supprimer des outils entre les requêtes brise le cache, car les définitions d’outils font partie du préfixe mis en cache.

La solution de l’équipe Claude Code : defer_loading. Au lieu d’inclure les schémas complets des outils, ils insèrent des stubs légers contenant uniquement le nom de l’outil et un flag defer_loading: true. Ces stubs restent dans le même ordre à chaque fois, ce qui maintient le préfixe de cache identique. Quand le modèle a réellement besoin du schéma complet d’un outil, il appelle un outil ToolSearch pour le charger à la demande.

Ce pattern est disponible dans l’API Anthropic aujourd’hui. Vous pouvez implémenter la même approche stub-et-recherche dans vos propres agents.

peakji de Manus a qualifié le taux de cache hit de métrique la plus déterminante pour les agents en production. Après hier, je partage entièrement cet avis.

La compression de contexte et son piège de cache

Quand une conversation remplit la fenêtre de contexte, il faut compresser : résumer l’historique et continuer dans une forme allégée. L’approche évidente consiste à appeler l’API avec un prompt de résumé. Mais si cet appel utilise un system prompt différent ou des définitions d’outils différentes, il ne correspondra pas au cache existant. Vous finissez par traiter l’intégralité d’une conversation de 100 000 tokens ou plus sans aucun bénéfice de cache, précisément au moment où les coûts sont les plus élevés.

Claude Code résout cela en réutilisant le system prompt exact et les définitions d’outils de la conversation parente pour l’appel de compression. Seul le dernier message utilisateur change, remplacé par une instruction de compression. Le préfixe mis en cache de la conversation parente correspond toujours, donc vous ne payez plein tarif que pour le nouveau message et la sortie du résumé.

Anthropic a depuis intégré ce pattern directement dans l’API comme fonctionnalité de compaction. Ils ont également publié l’auto-caching, où définir cache_control une seule fois dans le corps de la requête gère automatiquement les points de rupture du cache.

Le taux de cache hit comme métrique opérationnelle

L’équipe Claude Code surveille le taux de cache hit comme une équipe ops surveille la disponibilité de ses services. Quand le chiffre baisse, c’est traité comme un incident.

Cette façon de voir a changé ma façon de concevoir les prompts. Chaque modification du system prompt, chaque réordonnancement d’outils, chaque changement de modèle en cours de session est un incident potentiel. Le token le moins cher est celui qui touche le cache, et j’ai appris hier à quel point l’alternative peut coûter cher.