Come Claude Code utilizza il 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.

Il prompt caching rende Claude Code più veloce e più efficiente dal punto di vista dei costi. Senza caching, l’API rielaborerebbe la tua 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 te, 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. 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: 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. Si comportano diversamente per il caching:

• Model: la cache è codificata per modello, quindi ogni modello ha la sua cache. Cambiare modelli ricalcola l’intera richiesta anche quando il contenuto è identico. Vedi Switching models di seguito.
• Effort level: non fa parte della chiave della cache o del prompt, quindi cambiarla a metà sessione non ha alcun effetto sulla cache.

​

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 o una riconnessione MCP possono sembrare gratuiti finché non noti il turno più lento che segue.

• Switching models
• Connecting or disconnecting an MCP server
• Denying an entire tool
• Compacting the conversation
• Upgrading Claude Code

​

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.

​

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 degli strumenti MCP disponibili per Claude cambia tra i turni. La causa più comune è un MCP 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. MCP tool search riduce quanto ogni strumento contribuisce al prefisso rimandando le definizioni complete degli strumenti, ma l’insieme dei nomi degli strumenti deve comunque rimanere stabile affinché la cache rimanga valida.

​

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 si trovano nel layer del prompt di sistema, quindi aggiungere o rimuovere una di queste regole a metà sessione invalida la cache nello stesso modo in cui un MCP server che si connette o disconnette lo fa. La modifica ha effetto al turno successivo sia che la aggiungi tramite /permissions o modificando direttamente un file di impostazioni. Solo un nome di strumento semplice, o la forma equivalente Bash(*), ha questo effetto. Le regole di negazione 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.

• Editing files in your repository
• Editing CLAUDE.md mid-session
• Changing output style
• Changing permission mode
• Invoking skills and commands
• Running /recap
• Rewinding the conversation
• Spawning a subagent

​

Editing files in your 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.

​

Editing CLAUDE.md mid-session

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 a metà 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. Nested CLAUDE.md files in subdirectories e rules with paths: frontmatter 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 a metà sessione non lo cambia retroattivamente.

​

Changing output style

Output style fa parte del prompt di sistema, che Claude Code legge una sola volta all’inizio della sessione. Cambiarlo tramite /config o l’impostazione outputStyle a metà 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.

​

Changing permission mode

Passare tra permission modes, 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 model switch.

​

Invoking skills and commands

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

​

Running /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.

​

Rewinding the conversation

/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 editing files in your 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.

​

Check cache performance

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: 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.

​

Disable 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: 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.

​

Related resources

• Lessons from building Claude Code: Prompt caching is everything: la logica di progettazione per la modalità piano, il caricamento differito degli strumenti e la compaction
• Explore the context window: cosa viene caricato nel contesto e quando
• Reduce token usage: strategie oltre il caching per gestire la dimensione del contesto
• Track and reduce costs: tracciamento dei token della cache e configurazione del TTL per i chiamanti dell’Agent SDK
• Prompt caching: il meccanismo API sottostante, i breakpoint e i prezzi