Comment Claude Code utilise le prompt caching

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Le prompt caching rend Claude Code plus rapide et plus rentable. Sans caching, l’API retraiterait votre historique complet à chaque tour. Avec le caching, elle réutilise ce qu’elle a déjà traité et ne fait du nouveau travail que pour ce qui a changé. Claude Code gère le prompt caching pour vous, sauf si vous le désactivez. Il est néanmoins utile de comprendre comment fonctionne le prompt caching, car certaines actions invalident le cache et rendent la réponse suivante plus lente et plus coûteuse pendant qu’il se reconstruit. Cette page couvre les actions qui le font, pourquoi certains paramètres attendent un redémarrage pour s’appliquer, et comment vérifier les performances du cache quand l’utilisation semble élevée.

​

Comment le cache est organisé

Chaque fois que vous envoyez un message dans Claude Code, il effectue une nouvelle requête API. Le modèle ne se souvient de rien entre les requêtes, donc Claude Code renvoie le contexte complet : le prompt système, votre contexte de projet, chaque message antérieur et résultat d’outil, et votre nouveau message. Le nouveau contenu est ajouté à la fin, ce qui signifie que la plupart de chaque requête est identique à celle précédente. Le prompt caching est la façon dont l’API évite de retraiter la partie qui n’a pas changé. L’API met en cache en faisant correspondre le début de chaque requête, appelé le préfixe, avec le contenu qu’elle a récemment traité. À un tour normal, le préfixe est la requête entière précédente et seul l’échange le plus récent est nouveau. La correspondance est exacte, donc un changement n’importe où dans le préfixe recalcule tout ce qui suit. Il n’y a pas de caching par fichier ou par segment. Voir comment fonctionne le prompt caching dans la référence API pour le mécanisme sous-jacent. Pour tirer le meilleur parti de la correspondance de préfixe, Claude Code organise chaque requête de sorte que le contenu qui change rarement entre les tours vient en premier : Un changement à la couche conversation laisse le prompt système et le contexte du projet en cache. Un changement au prompt système invalide tout, car tout le contenu ultérieur se trouve maintenant derrière un préfixe différent. La troisième colonne donne les déclencheurs courants plutôt qu’une liste exhaustive, et les sections ci-dessous couvrent l’ensemble complet, y compris le contenu tel que le style de sortie qui est fixé au démarrage de la session. La règle de correspondance de préfixe explique la plupart des comportements sur cette page. Le mode plan et le chargement de compétences, par exemple, ajoutent leurs instructions comme messages de conversation, de sorte que le préfixe en cache reste intact. Deux paramètres ne font pas du tout partie du texte du prompt, donc ils n’apparaissent pas dans le tableau des couches. Ils se comportent différemment pour le caching :

• Modèle : le cache est indexé par modèle, donc chaque modèle a son propre cache. Changer de modèle recalcule la requête entière même quand le contenu est identique. Voir Changer de modèle ci-dessous.
• Niveau d’effort : ne fait pas partie de la clé de cache ou du prompt, donc le changer en cours de session n’a aucun effet sur le cache.

​

Où vit le cache

Le caching se produit côté serveur, dans l’infrastructure qui sert votre modèle. L’endroit où cela se trouve dépend de la façon dont vous vous authentifiez :

• Clé API, abonnement Claude, ou Claude Platform on AWS : le cache vit dans l’infrastructure d’Anthropic, accessible via l’API Claude
• Bedrock ou Vertex AI : le cache vit dans l’infrastructure de service de votre fournisseur cloud
• Foundry : les requêtes sont acheminées vers l’infrastructure d’Anthropic
• ANTHROPIC_BASE_URL personnalisé ou passerelle LLM : le cache vit là où vos requêtes sont transférées, et le fonctionnement du caching dépend de la passerelle

Pour ce que chaque fournisseur stocke et traite, voir utilisation des données. Où que le cache vive, les entrées expirent après une période d’inactivité, et Durée de vie du cache ci-dessous couvre le TTL et comment l’étendre.

​

Actions qui invalident le cache

Ces actions font que la requête suivante manque une partie ou la totalité du cache. Vous voyez un tour plus lent et plus coûteux une seule fois, après quoi le nouveau préfixe est mis en cache. La plupart d’entre elles sont évitables en cours de tâche une fois que vous savez qu’elles ont un coût. Un changement de modèle ou une reconnexion MCP peut sembler gratuit jusqu’à ce que vous remarquiez le tour plus lent qui suit.

• Changer de modèle
• Connecter ou déconnecter un serveur MCP
• Refuser un outil entier
• Compacter la conversation
• Mettre à niveau Claude Code

​

Changer de modèle

Chaque modèle a son propre cache. Changer avec /model signifie que la requête suivante lit l’historique de conversation entier sans cache hits, même si le contenu est identique. Le paramètre de modèle opusplan se résout en Opus pendant le mode plan et Sonnet pendant l’exécution, donc chaque basculement de mode plan est un changement de modèle et démarre un cache frais.

​

Connecter ou déconnecter un serveur MCP

Les définitions d’outils se trouvent dans la couche du prompt système, donc le cache s’invalide quand l’ensemble des outils MCP disponibles pour Claude change entre les tours. La cause la plus courante est un serveur MCP qui se connecte ou se déconnecte en cours de session, ce qui peut se produire sans aucune action de votre part : le processus d’un serveur stdio se termine, une session HTTP expire, ou un serveur se reconnecte automatiquement après une défaillance transitoire. Un serveur connecté peut également envoyer une mise à jour d’outil dynamique qui change sa liste d’outils. Éditer votre configuration MCP ne change pas le cache en soi. La nouvelle configuration ne prend effet qu’après un redémarrage, c’est à ce moment que le serveur se connecte ou se déconnecte. La recherche d’outils MCP réduit la contribution de chaque outil au préfixe en différant les définitions d’outils complètes, mais l’ensemble des noms d’outils doit rester stable pour que le cache reste valide.

​

Refuser un outil entier

Ajouter un nom d’outil simple comme Bash ou WebFetch comme règle de refus supprime cet outil du contexte de Claude entièrement. Les définitions d’outils se trouvent dans la couche du prompt système, donc ajouter ou supprimer l’une de ces règles en cours de session invalide le cache de la même manière qu’un serveur MCP qui se connecte ou se déconnecte. Le changement prend effet au tour suivant, que vous l’ajoutiez via /permissions ou en éditant un fichier de paramètres directement. Seul un nom d’outil simple, ou la forme équivalente Bash(*), a cet effet. Les règles de refus délimitées comme Bash(rm *), et toutes les règles d’autorisation et de demande, ne changent pas les outils que Claude voit. Claude Code les vérifie quand Claude tente un appel, laissant le préfixe intact.

​

Compacter la conversation

La compaction remplace votre historique de messages par un résumé. Par conception, cela invalide la couche conversation, puisque la requête suivante a un nouvel historique plus court qui ne partage pas de préfixe avec l’ancien. Claude Code réutilise la couche du prompt système et recharge le contexte du projet à partir du disque, qui ne cache que si CLAUDE.md et la mémoire sont inchangés depuis le début de la session. Pour produire le résumé, Claude Code envoie une requête unique avec le même prompt système, les mêmes outils et le même historique que votre conversation, plus une instruction de résumé ajoutée comme dernier message utilisateur. Parce qu’elle partage votre préfixe, cette requête lit le cache existant plutôt que de retraiter l’historique complet. La plupart du temps de compaction va à la génération du résumé, pas à un cache miss. Le tour qui suit reconstruit le cache de conversation uniquement pour le résumé beaucoup plus court, donc le tour post-compaction n’est pas la partie lente.

​

Mettre à niveau Claude Code

Une nouvelle version de Claude Code met généralement à jour le prompt système ou les définitions d’outils, donc la première requête après une mise à niveau reconstruit le cache à partir du début. La mise à jour automatique télécharge les nouvelles versions en arrière-plan mais les applique au prochain lancement, jamais en cours de session, donc vous voyez cela comme un premier tour sans cache après redémarrage plutôt qu’une surprise pendant une session. Définissez DISABLE_AUTOUPDATER=1 pour contrôler quand les mises à niveau s’appliquent.

​

Actions qui conservent le cache

Ces actions ajoutent soit à la fin de la conversation, soit ne touchent pas du tout la requête. Certaines d’entre elles, comme éditer CLAUDE.md ou changer le style de sortie, sont aussi pourquoi un changement de paramètre attend un redémarrage pour s’appliquer.

• Éditer des fichiers dans votre référentiel
• Éditer CLAUDE.md en cours de session
• Changer le style de sortie
• Changer le mode de permission
• Invoquer des compétences et des commandes
• Exécuter /recap
• Rembobiner la conversation
• Générer un sous-agent

​

Éditer des fichiers dans votre référentiel

Le contenu des fichiers entre en contexte uniquement quand Claude les lit, et les lectures s’ajoutent à la conversation. Éditer un fichier que Claude a précédemment lu ne change pas rétroactivement la lecture antérieure dans l’historique. Au lieu de cela, Claude Code ajoute un <system-reminder> notant que le fichier a changé, et Claude le relit si nécessaire.

​

Éditer CLAUDE.md en cours de session

Vos fichiers CLAUDE.md au niveau de la racine du projet et au niveau utilisateur sont lus une fois au démarrage de la session et conservés en mémoire. Les éditer en cours de session n’invalide pas le cache, mais l’édition ne s’applique pas non plus. Claude continue de travailler avec la version qui a été chargée au démarrage de la session. Le nouveau contenu se charge au prochain /clear, /compact, ou redémarrage. Les fichiers CLAUDE.md imbriqués dans les sous-répertoires et les règles avec frontmatter paths: se chargent plus tard, quand Claude lit pour la première fois un fichier correspondant. Éditer un avant qu’il se charge prend effet. Après son chargement, le contenu fait partie de l’historique de conversation, donc une édition en cours de session ne le change pas rétroactivement.

​

Changer le style de sortie

Le style de sortie fait partie du prompt système, que Claude Code lit une fois au démarrage de la session. Le changer via /config ou le paramètre outputStyle en cours de session n’invalide pas le cache, mais le changement ne s’applique pas non plus. Claude continue d’utiliser le style qui a été chargé au démarrage de la session. Le nouveau style se charge au prochain /clear ou redémarrage.

​

Changer le mode de permission

Basculer entre les modes de permission, comme du défaut à accepter les éditions, ne change pas le prompt système ou les définitions d’outils, donc les changements de mode sont sûrs pour le cache. L’exception est le mode plan avec le paramètre de modèle opusplan, qui bascule le modèle entre Opus et Sonnet quand vous entrez ou quittez le mode plan. Cela rend le basculement de mode un changement de modèle.

​

Invoquer des compétences et des commandes

Les compétences et les commandes injectent leurs instructions comme messages utilisateur au point d’invocation. Rien d’antérieur dans la conversation ne change.

​

Exécuter /recap

/recap génère un résumé pour l’affichage dans votre terminal. Contrairement à /compact, il ajoute le résumé comme sortie de commande plutôt que de remplacer votre historique de messages, de sorte que le préfixe en cache reste intact.

​

Rembobiner la conversation

/rewind tronque votre conversation jusqu’à un tour antérieur. L’historique restant est le même contenu à partir duquel le cache a été construit à ce moment, et les couches du prompt système et du contexte du projet sont inchangées, donc la requête suivante atteint l’entrée de cache antérieure. Chaque tour depuis a lu ce préfixe, ce qui a gardé l’entrée active même si le tour original était plus loin que le TTL. Restaurer les points de contrôle de fichiers aux côtés de la conversation n’a aucun effet séparé sur le cache. Le contenu des fichiers entre en contexte uniquement quand Claude les lit, comme éditer des fichiers dans votre référentiel.

​

Durée de vie du cache

Les préfixes en cache expirent après une période d’inactivité. Chaque requête qui atteint le cache réinitialise le minuteur, de sorte que le cache reste actif tant que vous continuez à travailler. Après un écart assez long, la requête suivante recalcule l’entrée complète et rétablit le cache, ce qui est pourquoi le premier tour après s’être éloigné peut être notablement plus lent. Le time to live (TTL) contrôle la durée de l’écart que le cache survit. L’API en offre deux : un TTL de cinq minutes, et un TTL d’une heure qui garde le cache actif pendant les pauses plus longues mais facture les écritures de cache à un taux plus élevé. Claude Code choisit le TTL pour vous en fonction de la façon dont vous vous authentifiez, et vous pouvez le remplacer avec des variables d’environnement.

​

Sur un abonnement Claude

Sur un abonnement Claude, Claude Code demande automatiquement le TTL d’une heure. L’utilisation est incluse dans votre plan plutôt que facturée par jeton, donc le TTL plus long ne vous coûte rien de plus et affecte uniquement la durée pendant laquelle votre cache reste actif. Si vous avez dépassé la limite d’utilisation de votre plan et que Claude Code puise dans les crédits d’utilisation, vous êtes facturé pour cette utilisation, donc Claude Code baisse automatiquement le TTL à cinq minutes.

​

Sur une clé API ou un fournisseur tiers

Sur une clé API, Bedrock, Vertex, Foundry, ou Claude Platform on AWS, vous payez les tarifs par jeton, donc le TTL reste aux cinq minutes moins chers par défaut. Pour opter pour le TTL d’une heure, définissez ENABLE_PROMPT_CACHING_1H=1. Sur Bedrock, le support du prompt caching, la longueur minimale du préfixe cacheable, et la disponibilité du TTL d’une heure varient tous selon le modèle. Si les comptages de jetons de cache restent à zéro, vérifiez les modèles, régions et limites pris en charge dans la documentation Bedrock.

​

Remplacer le TTL

Définissez FORCE_PROMPT_CACHING_5M=1 pour forcer le TTL de cinq minutes indépendamment de l’authentification. Ceci est utile quand vous déboguez le comportement du cache, comparez les deux TTL, ou remplacez un ENABLE_PROMPT_CACHING_1H défini dans les paramètres gérés.

​

Portée du cache

Dans Claude Code, le cache est effectivement limité à une machine et un répertoire. Le prompt système intègre le répertoire de travail, la plateforme, le shell, la version du système d’exploitation, et les chemins de mémoire automatique, donc deux sessions dans des répertoires différents construisent des préfixes différents et manquent le cache de l’autre. Cela inclut les worktrees du même référentiel, puisque chaque worktree a son propre répertoire de travail. Les sessions que vous exécutez en parallèle dans le même répertoire construisent des préfixes correspondants et lisent le cache de l’autre. Les sessions séquentielles partagent le préfixe uniquement quand l’instantané du statut git au démarrage correspond, puisque le prompt système capture également la branche et les commits récents. Le cache API sous-jacent est plus large. Les caches sont isolés entre les organisations, et sur certains fournisseurs, entre les espaces de travail au sein d’une organisation. Dans ces limites, deux requêtes quelconques avec le même modèle et préfixe lisent le même cache. Pour les appelants du SDK Agent exécutant des flottes de processus automatisés, voir améliorer le prompt caching entre les utilisateurs et les machines pour supprimer les sections par machine du prompt système et partager le cache entre les machines.

​

Vérifier les performances du cache

Les performances du cache s’affichent comme deux comptages de jetons que l’API rapporte sur chaque réponse. Le moyen le plus direct de les regarder en direct est un script de ligne d’état qui lit l’objet current_usage : Un ratio lecture-création élevé signifie que le caching fonctionne bien. Si la création reste élevée tour après tour, quelque chose change dans votre préfixe. La section Actions qui invalident le cache énumère les causes habituelles. Pour la visibilité dans une organisation, l’exportateur OpenTelemetry rapporte les jetons de lecture et de création du cache par utilisateur et session. Voir Surveiller l’utilisation pour la référence des attributs de métrique et d’événement.

​

Sous-agents et le cache

Un sous-agent démarre sa propre conversation avec son propre prompt système et ensemble d’outils, séparé du parent. Il construit son propre cache, en commençant sans cache hits à son premier appel et en se réchauffant à travers ses propres tours. Les sous-agents utilisent le TTL de cinq minutes même sur un abonnement, puisque le TTL d’une heure automatique s’applique à la conversation principale. Le cache du parent n’est pas affecté. Du côté du parent, l’appel du sous-agent et le résultat s’ajoutent à la conversation, laissant le préfixe du parent intact. Un fork, en contraste, hérite du prompt système du parent, des outils, et de l’historique de conversation exactement, donc sa première requête lit le cache du parent. L’appel de résumé de compaction décrit dans Compacter la conversation utilise la même approche de partage de préfixe.

​

Désactiver le prompt caching

Désactiver le caching est occasionnellement utile quand on débogue le comportement du caching avec un modèle ou un fournisseur spécifique. Pour l’éteindre, définissez l’une de ces variables d’environnement à 1 : Pour définir la politique de caching dans une organisation, mettez l’une de ces variables ou les variables TTL dans le bloc env des paramètres gérés. Pour un usage normal, laissez le caching activé.

​

Ressources connexes

• Leçons de la construction de Claude Code : Le prompt caching est tout : la justification de la conception pour le mode plan, le chargement d’outils différé, et la compaction
• Explorer la fenêtre de contexte : ce qui se charge en contexte et quand
• Réduire l’utilisation des jetons : stratégies au-delà du caching pour gérer la taille du contexte
• Suivre et réduire les coûts : suivi des jetons de cache et configuration du TTL pour les appelants du SDK Agent
• Prompt caching : le mécanisme API sous-jacent, les points d’arrêt, et la tarification