SpyBara
Go Premium

prompt-caching.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

35 added, 32 removed.

2026
Tue 30 23:02 Mon 29 23:02 Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Come Claude Code utilizza il prompt caching

Claude Code gestisce il prompt caching automaticamente. Scopri perché un cambio di modello attiva un turno lento senza cache, quanto costa /compact, perché le modifiche a CLAUDE.md non si applicano a metà sessione e come controllare il tasso di cache hit.

Il prompt caching rende Claude Code più veloce e più efficiente dal punto di vista dei costi. Senza caching, l'API rielaborerebbe la vostra cronologia completa ad ogni turno. Con il caching, riutilizza ciò che ha già elaborato e fa solo il nuovo lavoro per ciò che è cambiato.

Claude Code gestisce il prompt caching per voi, a meno che non lo disabiliti. È comunque utile sapere come funziona il prompt caching, perché alcune azioni invalidano la cache e rendono la risposta successiva più lenta e più costosa mentre la ricostruisce. Questa pagina copre quali azioni sono quelle, perché alcune impostazioni attendono un riavvio per applicarsi e come controllare le prestazioni della cache quando l'utilizzo sembra elevato.

Come è organizzata la cache

Ogni volta che invii un messaggio in Claude Code, effettua una nuova richiesta API. Il modello non ricorda nulla tra le richieste, quindi Claude Code rinvia il contesto completo: il prompt di sistema, il contesto del tuo progetto, ogni messaggio precedente e risultato dello strumento, e il tuo nuovo messaggio. Il nuovo contenuto viene aggiunto alla fine, il che significa che la maggior parte di ogni richiesta è identica a quella precedente. Il prompt caching è il modo in cui l'API evita di rielaborare la parte che non è cambiata.

L'API memorizza nella cache abbinando l'inizio di ogni richiesta, chiamato prefisso, al contenuto che ha elaborato di recente. Su un turno normale, il prefisso è l'intera richiesta precedente e solo lo scambio più recente è nuovo. La corrispondenza è esatta, quindi una modifica in qualsiasi punto del prefisso ricalcola tutto ciò che viene dopo. Non esiste caching per file o per segmento. Vedi come funziona il prompt caching nel riferimento API per il meccanismo sottostante.

Quattro turni mostrati come barre orizzontali crescenti. La richiesta di ogni turno contiene tutto dal turno precedente più lo scambio più recente aggiunto alla fine. Nei turni due e tre, il prefisso invariato viene letto dalla cache e solo il nuovo scambio viene elaborato. Nel turno quattro, il prompt di sistema è cambiato, quindi il prefisso non corrisponde più e l'intera richiesta viene rielaborata e scritta. Quattro turni mostrati come barre orizzontali crescenti. La richiesta di ogni turno contiene tutto dal turno precedente più lo scambio più recente aggiunto alla fine. Nei turni due e tre, il prefisso invariato viene letto dalla cache e solo il nuovo scambio viene elaborato. Nel turno quattro, il prompt di sistema è cambiato, quindi il prefisso non corrisponde più e l'intera richiesta viene rielaborata e scritta.

Per ottenere il massimo dall'abbinamento dei prefissi, Claude Code ordina ogni richiesta in modo che il contenuto che cambia raramente tra i turni venga per primo:

Layer Contenuto Cambia quando
System prompt Istruzioni principali, definizioni degli strumenti, stile di output Il set di definizioni degli strumenti caricati cambia, o Claude Code viene aggiornato
Project context CLAUDE.md, memoria automatica, regole non scoped La sessione inizia, o dopo /clear o /compact
Conversation I tuoi messaggi, le risposte di Claude, i risultati degli strumenti Ogni turno

Una modifica al layer della conversazione lascia il prompt di sistema e il contesto del progetto memorizzati nella cache. Una modifica al prompt di sistema invalida tutto, perché tutto il contenuto successivo ora si trova dietro un prefisso diverso. La terza colonna fornisce trigger comuni piuttosto che un elenco esaustivo, e le sezioni seguenti coprono l'insieme completo, incluso contenuto come lo stile di output che è fisso all'inizio della sessione.

La regola di abbinamento dei prefissi spiega la maggior parte dei comportamenti in questa pagina. Plan mode e skill loading, ad esempio, aggiungono le loro istruzioni come messaggi di conversazione, quindi il prefisso memorizzato nella cache rimane intatto.

Due impostazioni non fanno parte del testo del prompt, quindi non compaiono nella tabella dei layer, ma entrambe fanno parte della chiave della cache:

  • Model: ogni modello ha la sua cache. Cambiare modelli ricalcola l'intera richiesta anche quando il contenuto è identico. Vedi Switching models di seguito.
  • Effort level: ogni livello di sforzo ha la sua cache per lo stesso modello. Cambiarlo a metà sessione ricalcola l'intera richiesta, e Claude Code ti chiede di confermare prima di applicare il cambiamento. Vedi Changing effort level di seguito.

Dove vive la cache

Il caching avviene lato server, nell'infrastruttura che serve il tuo modello. Dove si trova dipende da come ti autentichi:

  • API key, Claude subscription, o Claude Platform on AWS: la cache vive nell'infrastruttura di Anthropic, accessibile tramite Claude API
  • Bedrock o Vertex AI: la cache vive nell'infrastruttura di servizio del tuo provider cloud
  • Foundry: le richieste vengono instradate all'infrastruttura di Anthropic
  • Custom ANTHROPIC_BASE_URL o LLM gateway: la cache vive dove vengono inoltrate le tue richieste, e se il caching funziona dipende dal gateway

Per ciò che ogni provider memorizza ed elabora, vedi data usage. Ovunque viva la cache, le voci scadono dopo un periodo di inattività, e Cache lifetime di seguito copre il TTL e come estenderlo.

Azioni che invalidano la cache

Queste azioni causano la mancanza di parte o tutta la cache nella richiesta successiva. Vedi un turno più lento e più costoso una sola volta, dopo il quale il nuovo prefisso viene memorizzato nella cache. La maggior parte di essi sono evitabili a metà compito una volta che sai che hanno un costo. Un cambio di modello può sembrare gratuito finché non noti il turno più lento che segue.

Switching models

Ogni modello ha la sua cache. Cambiare con /model significa che la richiesta successiva legge l'intera cronologia della conversazione senza cache hit, anche se il contenuto è identico.

L'impostazione opusplan model si risolve in Opus durante la modalità piano e Sonnet durante l'esecuzione, quindi ogni toggle della modalità piano è un cambio di modello e avvia una cache fresca.

Il fallback automatico del modello su Fable 5 è anche un cambio di modello. Quando un classificatore di sicurezza contrassegna una richiesta, Claude Code la riesegue sul modello Opus predefinito e la sessione continua lì.

Changing effort level

La cache è codificata dal livello di effort così come dal modello, quindi cambiare con /effort significa che la richiesta successiva legge l'intera cronologia della conversazione senza cache hit. Una volta che una conversazione è iniziata, Claude Code mostra una finestra di dialogo di conferma prima di applicare un cambio di effort che invaliderebbe la cache. Un cambio che si risolve nello stesso livello già in vigore, come impostare esplicitamente il valore predefinito del modello, salta la finestra di dialogo e mantiene la cache.

Turning on fast mode

L'abilitazione della fast mode aggiunge un'intestazione di richiesta che fa parte della chiave della cache, quindi la richiesta successiva legge l'intera cronologia della conversazione senza cache hit. Quei token di input non memorizzati nella cache vengono fatturati alle tariffe della fast mode, motivo per cui attivarla all'inizio di una sessione costa meno che attivarla in profondità in una sessione lunga. L'abilitazione della fast mode da un modello non-Opus cambia anche il tuo modello, il che avvia una cache fresca di per sé.

Il costo si applica una volta per conversazione. Dopo il primo turno della fast mode, Claude Code continua a inviare l'intestazione e varia solo l'impostazione di velocità della richiesta, che non fa parte della chiave della cache. Disattivare la fast mode, il fallback automatico alla velocità standard dopo un limite di velocità, e riattivarla in seguito mantengono tutti la cache. /clear e /compact ripristinano questo, poiché ricostruiscono la cache in quei punti comunque.

Connecting or disconnecting an MCP server

Le definizioni degli strumenti si trovano nel layer del prompt di sistema, quindi la cache si invalida quando l'insieme delle definizioni degli strumenti nella richiesta cambia tra i turni. Attivare lo strumento advisor è un'eccezione: la sua definizione si trova dopo il punto di interruzione della cache, quindi abilitare o disabilitare /advisor mantiene il prefisso memorizzato nella cache intatto. Se un cambio di MCP server fa questo dipende dal fatto che i suoi strumenti siano rimandati dalla tool search o caricati nel prefisso:

  • Strumenti rimandati, il valore predefinito sui modelli supportati: un server che si connette, disconnette, o cambia il suo elenco di strumenti aggiunge solo nuovo contenuto e non disturba nulla che sia già memorizzato nella cache.
  • Strumenti caricati nel prefisso: qualsiasi cambio ad essi invalida la cache. Questo accade quando tool search non è disponibile o disabilitato, come sui modelli Haiku, su Vertex AI, o con un gateway ANTHROPIC_BASE_URL personalizzato. Accade anche per un server o uno strumento contrassegnato alwaysLoad, e per le definizioni mantenute in primo piano dal caricamento basato su soglia.

Quando gli strumenti si caricano nel prefisso, la causa più comune di un'invalidazione è un server che si connette o disconnette a metà sessione, il che può accadere senza alcuna azione da parte tua: il processo di un server stdio esce, una sessione HTTP scade, o un server si riconnette automaticamente dopo un errore transitorio. Un server connesso può anche inviare un dynamic tool update che cambia il suo elenco di strumenti.

Modificare la tua configurazione MCP non cambia la cache di per sé. La nuova configurazione ha effetto solo dopo un riavvio, che è quando il server si connette o disconnette.

Enabling or disabling a plugin

I plugin raggruppano diversi tipi di componenti, e il costo di un cambio dipende da quali componenti il plugin fornisce. Skills, comandi, agenti, hooks, server LSP, monitor e temi non invalidano mai la cache: qualsiasi cosa aggiungano alla richiesta viene aggiunta dopo la conversazione esistente, quindi la richiesta successiva paga per il nuovo contenuto ma legge comunque tutto ciò che lo precede dalla cache.

L'eccezione è un plugin che fornisce MCP server. Abilitare o disabilitare uno segue le stesse regole di connessione o disconnessione di un MCP server: la cache sopravvive quando gli strumenti del server sono rimandati, e la richiesta successiva rilegge l'intera conversazione quando si caricano nel prefisso.

I cambiamenti dei plugin si applicano quando esegui /reload-plugins o avvii una nuova sessione. Il costo, sia annunci aggiunti che una rilettura completa, si mostra al primo turno dopo il ricaricamento, non quando esegui /plugin install, /plugin enable, o /plugin disable. {/* min-version: 2.1.163 */}A partire da v2.1.163, quando un ricaricamento attiverebbe la rilettura completa, /reload-plugins mostra un avviso e non applica il ricaricamento. Passa --force per applicare comunque.

Disabilitare un plugin che hai abilitato in precedenza nella sessione ripristina la forma di richiesta precedente. Se quel prefisso è ancora entro la sua durata della cache, la richiesta successiva legge la voce di cache più vecchia invece di ricostruirla.

Denying an entire tool

Aggiungere un nome di strumento semplice come Bash o WebFetch come deny rule rimuove completamente quello strumento dal contesto di Claude. Le definizioni degli strumenti incorporati si caricano nel layer del prompt di sistema, quindi aggiungere o rimuovere una di queste regole a metà sessione invalida la cache. La modifica ha effetto al turno successivo sia che la aggiungi tramite /permissions o modificando direttamente un file di impostazioni.

Solo una deny rule che corrisponde nella posizione del nome dello strumento ha questo effetto: un nome di strumento semplice, la forma equivalente Bash(*), o un tool-name glob come "*". Un glob che corrisponde solo agli strumenti MCP, come "mcp__*", rimuove quegli strumenti allo stesso modo ma lascia la cache intatta quando gli strumenti corrispondenti sono rimandati, il valore predefinito, poiché le definizioni rimandate non erano mai nel prefisso memorizzato nella cache. Le deny rule con ambito come Bash(rm *), e tutte le regole di consentimento e richiesta, non cambiano quali strumenti Claude vede. Claude Code le controlla quando Claude tenta una chiamata, lasciando il prefisso intatto.

Compacting the conversation

Compaction sostituisce la tua cronologia dei messaggi con un riepilogo. Per progettazione, questo invalida il layer della conversazione, poiché la richiesta successiva ha una cronologia nuova e più breve che non condivide un prefisso con quella vecchia. Claude Code riutilizza il layer del prompt di sistema e ricarica il contesto del progetto dal disco, che ha cache hit solo se CLAUDE.md e la memoria sono invariati dall'inizio della sessione.

Per produrre il riepilogo, Claude Code invia una richiesta una tantum con lo stesso prompt di sistema, strumenti e cronologia della tua conversazione, più un'istruzione di riepilogo aggiunta come messaggio utente finale. Poiché condivide il tuo prefisso, quella richiesta legge la cache esistente piuttosto che rielaborare la cronologia completa. La maggior parte del tempo di compaction va alla generazione del riepilogo, non a una cache miss. Il turno che segue ricostruisce la cache della conversazione solo per il riepilogo molto più breve, quindi il turno post-compaction non è la parte lenta.

Upgrading Claude Code

Una nuova versione di Claude Code in genere aggiorna il prompt di sistema o le definizioni degli strumenti, quindi la prima richiesta dopo un aggiornamento ricostruisce la cache dall'inizio. Auto-update scarica le nuove versioni in background ma le applica al prossimo avvio, mai a metà sessione, quindi lo vedi come un primo turno senza cache dopo il riavvio piuttosto che una sorpresa durante una sessione. Imposta DISABLE_AUTOUPDATER=1 per controllare quando gli aggiornamenti si applicano.

Azioni che mantengono la cache

Queste azioni aggiungono alla fine della conversazione o non toccano affatto la richiesta. Alcune di esse, come modificare CLAUDE.md o cambiare lo stile di output, sono anche il motivo per cui una modifica dell'impostazione attende un riavvio per applicarsi.

Modifica dei file nel tuo repository

I contenuti dei file entrano nel contesto solo quando Claude li legge, e le letture si aggiungono alla conversazione. Modificare un file che Claude ha letto in precedenza non cambia retroattivamente la lettura precedente nella cronologia. Invece, Claude Code aggiunge un <system-reminder> notando che il file è cambiato, e Claude lo rilegge se necessario.

Modifica di CLAUDE.md durante la sessione

I tuoi file CLAUDE.md a livello di radice del progetto e a livello utente vengono letti una sola volta all'inizio della sessione e mantenuti in memoria. Modificarli durante la sessione non invalida la cache, ma la modifica non si applica nemmeno. Claude continua a lavorare con la versione che è stata caricata all'inizio della sessione. Il nuovo contenuto viene caricato al prossimo /clear, /compact o riavvio.

I file CLAUDE.md annidati nelle sottodirectory e le regole con frontmatter paths: vengono caricati in seguito, quando Claude legge per la prima volta un file corrispondente. Modificarne uno prima che venga caricato ha effetto. Dopo che viene caricato, il contenuto fa parte della cronologia della conversazione, quindi una modifica durante la sessione non lo cambia retroattivamente.

Cambio dello stile di output

Lo stile di output fa parte del prompt di sistema, che Claude Code legge una sola volta all'inizio della sessione. Cambiarlo tramite /config o l'impostazione outputStyle durante la sessione non invalida la cache, ma il cambiamento non si applica nemmeno. Claude continua a usare lo stile che è stato caricato all'inizio della sessione. Il nuovo stile viene caricato al prossimo /clear o riavvio.

Cambio della modalità di autorizzazione

Passare tra modalità di autorizzazione, come da predefinito ad accettare modifiche, non cambia il prompt di sistema o le definizioni degli strumenti, quindi i cambi di modalità sono sicuri per la cache. L'eccezione è la modalità piano con l'impostazione opusplan del modello, che cambia il modello tra Opus e Sonnet quando entri o esci dalla modalità piano. Questo rende il toggle della modalità un cambio di modello.

Invocazione di skills e comandi

Skills e comandi iniettano le loro istruzioni come messaggi utente nel punto di invocazione. Nulla prima nella conversazione cambia.

Esecuzione di `/recap`

/recap genera un riepilogo per la visualizzazione nel tuo terminale. A differenza di /compact, aggiunge il riepilogo come output del comando piuttosto che sostituire la tua cronologia dei messaggi, quindi il prefisso memorizzato nella cache rimane intatto.

Riavvolgimento della conversazione

/rewind tronca la tua conversazione a un turno precedente. La cronologia rimanente è lo stesso contenuto da cui la cache è stata costruita in quel momento, e i layer del prompt di sistema e del contesto del progetto sono invariati, quindi la richiesta successiva colpisce la voce della cache precedente. Ogni turno da allora ha letto attraverso quel prefisso, che ha mantenuto la voce calda anche se il turno originale era più tempo fa del TTL.

Il ripristino dei checkpoint dei file insieme alla conversazione non ha alcun effetto separato sulla cache. I contenuti dei file entrano nel contesto solo quando Claude li legge, come modifica dei file nel tuo repository.

Cache lifetime

I prefissi memorizzati nella cache scadono dopo un periodo di inattività. Ogni richiesta che colpisce la cache ripristina il timer, quindi la cache rimane calda finché continui a lavorare. Dopo un intervallo abbastanza lungo, la richiesta successiva ricalcola l'input completo e ristabilisce la cache, il che è il motivo per cui il primo turno di ritorno dopo essersi allontanato può essere notevolmente più lento.

Il time to live (TTL) controlla per quanto tempo un intervallo la cache sopravvive. L'API offre due: un TTL di cinque minuti e un TTL di un'ora che mantiene la cache calda attraverso pause più lunghe ma fattura le scritture della cache a una velocità più elevata. Claude Code sceglie il TTL per te in base a come ti autentichi, e puoi sovrascriverlo con variabili di ambiente.

On a Claude subscription

Su una Claude subscription, Claude Code richiede automaticamente il TTL di un'ora. L'utilizzo è incluso nel tuo piano piuttosto che fatturato per token, quindi il TTL più lungo non ti costa nulla in più e influisce solo su quanto tempo la tua cache rimane calda.

Se hai superato il limite di utilizzo del tuo piano e Claude Code sta attingendo ai usage credits, ti viene fatturato quell'utilizzo, quindi Claude Code abbassa automaticamente il TTL a cinque minuti.

On an API key or third-party provider

Su una API key, Bedrock, Vertex, Foundry, o Claude Platform on AWS, paghi le tariffe per token, quindi il TTL rimane ai cinque minuti più economici per impostazione predefinita. Per optare per il TTL di un'ora, imposta ENABLE_PROMPT_CACHING_1H=1.

Su Bedrock, il supporto del prompt caching, la lunghezza minima del prefisso memorizzabile nella cache e la disponibilità del TTL di un'ora variano a seconda del modello. Se i conteggi dei token della cache rimangono a zero, controlla supported models, regions, and limits nella documentazione di Bedrock.

Override the TTL

Imposta FORCE_PROMPT_CACHING_5M=1 per forzare il TTL di cinque minuti indipendentemente dall'autenticazione. Questo è utile quando stai eseguendo il debug del comportamento della cache, confrontando i due TTL, o sovrascrivendo un ENABLE_PROMPT_CACHING_1H impostato in managed settings.

Cache scope

In Claude Code, la cache è effettivamente scoped a una macchina e una directory. Il prompt di sistema incorpora la directory di lavoro, la piattaforma, la shell, la versione del sistema operativo e i percorsi della memoria automatica, quindi due sessioni in directory diverse costruiscono prefissi diversi e si perdono la cache l'una dell'altra. Questo include i worktrees dello stesso repository, poiché ogni worktree ha la sua directory di lavoro.

Le sessioni che esegui in parallelo nella stessa directory costruiscono prefissi corrispondenti e leggono la cache l'una dell'altra. Le sessioni sequenziali condividono il prefisso solo quando lo snapshot dello stato git all'avvio corrisponde, poiché il prompt di sistema cattura anche il ramo e i commit recenti.

La cache API sottostante è più ampia. Le cache sono isolate tra le organizzazioni e, su alcuni provider, tra i workspace all'interno di un'organizzazione. All'interno di questi confini, qualsiasi due richieste con lo stesso modello e prefisso leggono la stessa cache. Per i chiamanti dell'Agent SDK che eseguono flotte di processi automatizzati, vedi improve prompt caching across users and machines per sopprimere le sezioni per macchina del prompt di sistema e condividere la cache tra le macchine.

Verificare le prestazioni della cache

Le prestazioni della cache si mostrano come due conteggi di token che l'API segnala su ogni risposta. Il modo più diretto per guardarli dal vivo è uno statusline script che legge l'oggetto current_usage:

Field Meaning
cache_creation_input_tokens Token scritti nella cache su questo turno, fatturati alla velocità di scrittura della cache
cache_read_input_tokens Token serviti dalla cache su questo turno, fatturati a circa il 10% della velocità di input standard

Un alto rapporto lettura-creazione significa che il caching funziona bene. Se la creazione rimane alta turno dopo turno, qualcosa sta cambiando nel tuo prefisso. La sezione actions that invalidate the cache elenca le cause usuali.

Per la visibilità in un'organizzazione, l'esportatore OpenTelemetry segnala i token di lettura e creazione della cache per utente e sessione. Vedi Monitor usage per il riferimento degli attributi di metrica e evento.

Subagents and the cache

Un subagent avvia la sua propria conversazione con il suo prompt di sistema e set di strumenti, separato da quello del genitore. Costruisce la sua propria cache, iniziando senza cache hit sulla sua prima chiamata e riscaldandosi attraverso i suoi turni. I subagent utilizzano il TTL di cinque minuti anche su una subscription, poiché il TTL di un'ora automatico si applica alla conversazione principale.

La cache del genitore non è interessata. Dal lato del genitore, la chiamata e il risultato del subagent si aggiungono alla conversazione, lasciando il prefisso del genitore intatto.

Un fork, al contrario, eredita il prompt di sistema, gli strumenti e la cronologia della conversazione del genitore esattamente, quindi la sua prima richiesta legge la cache del genitore. La chiamata di riepilogo della compaction descritta in Compacting the conversation utilizza lo stesso approccio di condivisione dei prefissi.

Disabilita prompt caching

Disabilitare il caching è occasionalmente utile quando si esegue il debug del comportamento della cache con un modello o provider specifico. Per disattivarlo, imposta una di queste variabili di ambiente su 1:

Variable Effect
DISABLE_PROMPT_CACHING Disabilita per tutti i modelli
DISABLE_PROMPT_CACHING_HAIKU Disabilita per Haiku solo
DISABLE_PROMPT_CACHING_SONNET Disabilita per Sonnet solo
DISABLE_PROMPT_CACHING_OPUS Disabilita per Opus solo
DISABLE_PROMPT_CACHING_FABLE Disabilita per Fable solo

Per impostare la politica di caching in un'organizzazione, metti una di queste o le TTL variables nel blocco env di managed settings. Per l'uso normale, lascia il caching abilitato.