Cet article technique de l'équipe Claude Code chez Anthropic révèle comment le prompt caching constitue le fondement architectural de Claude Code, rendant économiquement viable un produit agentique à sessions longues. Le principe fondamental : le cache fonctionne par correspondance de préfixe, toute modification dans le préfixe invalidant tout ce qui suit. Cette contrainte unique dicte la conception de l'ensemble du système.
L'architecture du system prompt suit un ordre strict : contenu statique et outils en premier (cache global), puis CLAUDE.MD (cache par projet), contexte de session, et enfin les messages de conversation. Cette hiérarchie maximise le partage de cache entre sessions. L'équipe a découvert que cet ordre est étonnamment fragile : un simple timestamp, un ordre d'outils non-déterministe ou la mise à jour de paramètres d'outils suffit à casser le cache.
Plusieurs règles contre-intuitives émergent de leur expérience. Premièrement, ne jamais modifier le system prompt pour des informations changeantes (date, fichiers modifiés) mais utiliser des balises <system-reminder> dans les messages suivants. Deuxièmement, ne jamais changer de modèle en cours de session : à 100k tokens de conversation avec Opus, utiliser Haiku pour une question simple coûte plus cher car le cache doit être entièrement reconstruit. La solution : les subagents avec un message de handoff. Troisièmement, ne jamais ajouter ou retirer d'outils, car ils font partie du préfixe caché.
Le plan mode illustre parfaitement le design contraint par le cache. Au lieu de remplacer les outils par des versions lecture seule (ce qui casserait le cache), Claude Code conserve tous les outils et utilise EnterPlanMode/ExitPlanMode comme outils supplémentaires, avec un system message explicatif. Ce design permet au modèle d'entrer en plan mode de lui-même sans rupture de cache. Le tool search applique le même principe : au lieu de retirer les outils MCP inutilisés, des stubs légers avec defer_loading: true maintiennent le préfixe stable.
La compaction (résumé lors du dépassement de la fenêtre de contexte) présente des pièges majeurs. L'implémentation naïve avec un appel API séparé (system prompt différent, sans outils) fait payer le prix complet de tous les tokens. La solution : utiliser exactement les mêmes paramètres que la conversation parente pour réutiliser le préfixe caché, en ne payant que les tokens du prompt de compaction.
L'article conclut que le taux de cache hit doit être surveillé comme l'uptime, avec alertes et incidents déclarés en cas de baisse. Ces patterns sont désormais intégrés directement dans l'API Anthropic, permettant à tout développeur d'agents de bénéficier de ces optimisations.