Leçon tirée de la création de Claude Code : le prompt caching est la clé de tout

• Dans les produits d’agents à longue exécution, le prompt caching est une technologie centrale qui réutilise les calculs des allers-retours précédents pour réduire drastiquement la latence et les coûts, et toute l’architecture de Claude Code a été conçue autour de ce principe
• Comme le caching fonctionne par correspondance de préfixe, l’ordre qui consiste à placer le contenu statique au début et le contenu dynamique à la fin détermine les coûts et les performances
• Si l’on change d’outil ou de modèle en cours de session, le cache est invalidé ; une conception de contournement utilisant des stubs légers et des outils de transition d’état au lieu de supprimer des outils est donc indispensable
• Même la compaction (résumé/réduction) effectuée lorsque la fenêtre de contexte est dépassée doit partager le préfixe en cache de la conversation parente afin d’éviter une explosion des coûts
• Il faut surveiller le taux de hit du cache comme un uptime et traiter quelques pourcents de cache miss comme un incident, tant leur impact sur les coûts et la latence peut être grave

---

• “Cache Rules Everything Around Me” s’applique aussi tel quel aux agents
• Le prompt caching rend possibles des produits d’agents de longue durée comme Claude Code
• Il permet de réduire fortement la latency et le cost en réutilisant les calculs des allers-retours précédents

Fonctionnement du prompt caching et placement du prompt système

• Le prompt caching fonctionne par correspondance de préfixe (Prefix), et l’API met en cache tout le contenu depuis le début de la requête jusqu’à chaque point d’arrêt cache_control
• Le point essentiel est de maximiser le préfixe partagé entre les requêtes ; pour cela, il faut placer le contenu statique d’abord, puis le contenu dynamique
• Ordre utilisé par Claude Code :
  • Prompt système statique et outils (cache global)
  • Claude.MD (cache au sein du projet)
  • Contexte de session (cache au sein de la session)
  • Messages de conversation
• Cet ordre est étonnamment fragile, et il peut y avoir invalidation du cache à cause, par exemple, de :
  insertion d’un timestamp détaillé dans le prompt système statique,
  mélange non déterministe de l’ordre des outils,
  mise à jour des paramètres des outils

Stratégie de mise à jour via les messages système

• Il existe des cas où les informations dans le prompt deviennent obsolètes, par exemple lorsque le temps change ou que l’utilisateur modifie des fichiers
• Mettre à jour directement le prompt entraîne des cache miss et peut augmenter les coûts pour l’utilisateur
• À la place, on utilise une transmission sous forme de message au tour suivant
  • Claude Code insère les informations mises à jour dans le prochain message utilisateur ou le résultat d’outil avec la balise <system-reminder>
  • Par exemple, pour signaler une mise à jour temporelle comme « nous sommes maintenant mercredi »
• Utiliser ainsi des system messages permet de préserver le cache

Pourquoi il ne faut pas changer de modèle en cours de session

• Le prompt cache est spécifique à chaque modèle, si bien que le calcul des coûts liés au caching peut être moins intuitif qu’il n’y paraît
• Exemple : dans une conversation de 100k tokens avec Opus, si l’on bascule vers Haiku pour une question simple, il faut reconstruire depuis zéro le cache pour Haiku, ce qui peut au final coûter plus cher que de répondre directement avec Opus
• Lorsqu’un changement de modèle est nécessaire, l’approche par sous-agent est la meilleure : Opus prépare alors un message de « handoff » qu’il transmet à un autre modèle
  • L’agent Explore de Claude Code applique cette méthode lorsqu’il utilise Haiku

Ne pas ajouter ni supprimer d’outils en cours de session

• Modifier l’ensemble des outils est l’une des causes les plus fréquentes d’invalidation du cache
• Comme les outils font partie du préfixe mis en cache, ajouter ou supprimer un seul outil invalide le cache de toute la conversation

• Plan Mode — une conception centrée sur le cache

  • Approche intuitive : lorsqu’un utilisateur entre en plan mode, ne garder que les outils en lecture seule → cela détruit le cache
  • Conception réelle : tous les outils sont toujours inclus dans la requête, et EnterPlanMode ainsi que ExitPlanMode sont implémentés comme des outils
    • Lors de l’entrée en plan mode, des instructions sont transmises via un message système : explorer uniquement la base de code, ne pas modifier les fichiers, puis appeler ExitPlanMode une fois terminé
    • Les définitions d’outils ne changent jamais
  • Avantage supplémentaire : comme EnterPlanMode est un outil que le modèle peut appeler directement, il peut entrer de manière autonome en plan mode lorsqu’il détecte un problème difficile, sans casser le cache

• Tool Search — chargement différé au lieu de suppression

  • Claude Code peut charger des dizaines d’outils MCP ; les inclure tous augmente les coûts, mais les supprimer détruit le cache
  • Solution : une approche defer_loading, qui envoie non pas une suppression d’outil mais un stub léger contenant seulement le nom (defer_loading: true)
    • Si le modèle en a besoin, il charge le schéma complet via l’outil ToolSearch
    • Comme les mêmes stubs sont toujours présents dans le même ordre, le préfixe mis en cache reste stable
  • La fonctionnalité tool search de l’API permet de simplifier cela

Forking de contexte — compaction (Compaction)

• Lorsque la fenêtre de contexte est dépassée, on effectue une compaction qui résume la conversation pour démarrer une nouvelle session
• Une implémentation intuitive (générer un résumé via un appel API séparé, avec un autre prompt système et sans outils) ne correspond pas du tout au préfixe mis en cache de la conversation principale, ce qui entraîne une facturation complète de tous les tokens d’entrée

• Solution de Cache-Safe Forking

  • Lors de la compaction, on utilise le même prompt système, le même contexte utilisateur, le même contexte système et les mêmes définitions d’outils que dans la conversation parente
  • On place d’abord les messages de la conversation parente, puis on ajoute à la fin le prompt de compaction comme nouveau message utilisateur
  • Du point de vue de l’API, cette requête ressemble presque à la dernière requête de la conversation parente ; elle peut donc réutiliser le préfixe mis en cache, et les seuls nouveaux tokens sont ceux du prompt de compaction
  • Il faut réserver dans la fenêtre de contexte un « buffer de compaction » pour le message compacté et les tokens de sortie du résumé
  • Sur la base de ce schéma, Anthropic a intégré directement une fonction de compaction dans l’API, que les développeurs peuvent utiliser eux-mêmes

Synthèse des leçons clés

• Le prompt caching repose sur une correspondance de préfixe ; si un changement survient n’importe où dans ce préfixe, tout le cache qui suit est invalidé → il faut concevoir l’ensemble du système autour de cette contrainte
• Au lieu de modifier le prompt système, insérer des messages système dans la conversation est plus favorable à la préservation du cache
• Ne changez pas d’outil ni de modèle en cours de conversation → modélisez les transitions d’état comme des outils, et utilisez le chargement différé plutôt que la suppression d’outils
• Il faut surveiller le taux de hit du cache comme un uptime ; même quelques pourcents de cache miss ont un impact spectaculaire sur les coûts et la latence
• Les tâches de fork (compaction, résumé, exécution de compétences) doivent partager le préfixe parent pour permettre un cache hit

• Si vous construisez un agent, il faut concevoir dès le premier jour autour du prompt caching