Claude Code: ridurre contesto, lentezza e costi

Come evitare che una sessione lunga di Claude Code diventi lenta e costosa

Una sessione lunga di Claude Code diventa lenta e costosa perché a ogni turno viene reinviato l’intero contesto, che continua a crescere. La soluzione è applicare una procedura di pulizia in un ordine prestabilito. Esegui /context per vedere quali elementi occupano la finestra di contesto, riduci quelli che vengono conteggiati a ogni richiesta, quindi usa /clear tra attività non correlate e /compact con un’istruzione all’interno di un’unica attività lunga. Lavora per sessioni continue, perché una cache del prompt fredda trasforma una lettura economica in una riscrittura completa di tutto ciò che hai detto.

Il motivo per cui il contatore aumenta è spiegato in il contatore dei token alla base di una sessione agent.

Leggi /context prima di modificare qualsiasi cosa

Non indovinare cosa riempie la finestra. Claude Code te lo comunicherà.

/context [all] mostra l'utilizzo attuale del contesto sotto forma di griglia colorata, con suggerimenti per l'ottimizzazione degli strumenti che usano molto contesto e della crescita eccessiva della memoria; all espande la suddivisione per elemento in modalità a schermo intero. Interpreta il risultato come cinque categorie.

• Il prompt di sistema. Le istruzioni del framework di Claude Code. Sono fisse per la sessione.
• Le definizioni degli strumenti. Lo schema di ogni strumento che l'agente può chiamare, inclusi tutti i server MCP (Model Context Protocol) connessi.
• I file di memoria. CLAUDE.md e la memoria automatica, caricati all'avvio della sessione.
• I file e i risultati degli strumenti. Ogni file letto e tutto ciò che i comandi restituiscono.
• La cronologia dei messaggi. I tuoi turni e le relative risposte.

I primi tre elementi costituiscono un costo fisso, sostenuto a ogni richiesta per tutta la durata della sessione. Gli ultimi due aumentano nel tempo. Riduci il costo fisso una volta, all'inizio; gestisci continuamente la parte crescente.

Due stringhe indicano che la finestra è piena:

Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.
Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.

La prima indica un limite rigido: la richiesta viene rifiutata e l'errore dell'API (application programming interface) corrispondente è Prompt is too long. La seconda indica una finestra di compattazione, che può essere inferiore alla finestra di contesto effettiva su un modello da 1 million di token. Le richieste continuano ad avere esito positivo oltre questa soglia, quindi si tratta di un avviso e non di un rifiuto.

Con un piano a pagamento, /usage aggiunge l'altra metà del monitoraggio: segnala comportamenti come l'uso di un contesto esteso o i cache miss e attribuisce l'utilizzo recente a singole competenze, sottoagenti e server MCP. Se indica che la quota è già esaurita, quale finestra del limite stai aspettando determina se ridurre il contesto ti aiuta subito o se devi seguire un percorso diverso per riprendere il lavoro.

CLAUDE.md è una tassa permanente, quindi mantienilo snello

Il tuo CLAUDE.md viene caricato nel contesto all'avvio della sessione e vi rimane. Se contiene una procedura di deployment dettagliata, quei token sono presenti anche mentre correggi un refuso in un file di test. La linea guida di Anthropic è includere solo l'essenziale e mantenere il file sotto le 200 righe.

Sposta le procedure nelle skill. Una skill viene caricata solo quando invocata, quindi un workflow che esegui due volte a settimana non ha costi negli altri giorni. Le skill hanno un proprio budget dopo una compattazione: i corpi vengono reinseriti, con un limite di 5.000 token per skill e 25.000 in totale, eliminando i più vecchi per primi. Il troncamento mantiene l'inizio del file, quindi inserisci le istruzioni più importanti vicino all'inizio di SKILL.md.

Ciò che sopravvive a una compattazione determina dove appartiene un'istruzione.

• Il prompt di sistema e lo stile di output rimangono invariati, poiché non fanno parte della cronologia dei messaggi.
• Il CLAUDE.md della root del progetto, le regole non delimitate e la memoria automatica vengono reinseriti dal disco.
• Una regola con frontmatter paths: viene persa finché non viene letto di nuovo un file corrispondente.
• Un CLAUDE.md annidato in una sottodirectory viene perso finché non viene letto di nuovo un file in quella sottodirectory.
• Gli hook continuano a essere eseguiti, poiché un hook viene eseguito come codice; solo il contesto aggiunto in precedenza da un hook viene riassunto insieme al resto della conversazione.

Quindi, una regola da cui dipendi appartiene al CLAUDE.md della root del progetto: Claude Code elimina prima gli output degli strumenti più vecchi e poi riassume, quindi le istruzioni all'inizio della conversazione potrebbero andare perse. Modifica la memoria con /memory. Claude Code mantiene la copia caricata all'avvio della sessione, quindi un taglio a metà sessione mantiene la cache del prompt e non viene applicato fino al successivo /clear, /compact o riavvio. La perdita di contesto è solo uno dei motivi per cui una regola smette di essere seguita, quindi quando la regola è chiaramente ancora nella finestra e viene comunque ignorata, analizza le altre cause prima di riscriverla.

/clear tra attività diverse, /compact all'interno della stessa

Questi due comandi sembrano intercambiabili, ma hanno costi molto diversi.

/clear [name] avvia una nuova conversazione senza contesto. Non invia alcuna richiesta, quindi non ha costi. Passa un nome per etichettare la conversazione precedente nel selettore /resume; /reset e /new sono alias. Usalo non appena passi a un'attività non correlata, perché altrimenti l'attività precedente verrebbe reinviata e fatturata di nuovo a ogni messaggio della nuova attività.

/compact [instructions] libera spazio nel contesto continuando la stessa conversazione: riassume la cronologia disponibile fino a quel momento e la sostituisce. Usalo all'interno di un'attività lunga, quando ti serve ancora la continuità.

Specifica sempre un'istruzione per /compact. Un semplice /compact crea il riepilogo usando un prompt predefinito che non sa quale parte del lavoro ti serva ancora. Se gli fornisci un'istruzione, la conserva:

/compact focus on the auth bug fix
/compact keep only the plan and the diff

Se usi il compattamento ogni volta per lo stesso motivo, inserisci un'istruzione permanente nel file CLAUDE.md del progetto, sotto un'intestazione # Compact instructions. In una nuova sessione, /compact stampa Not enough messages to compact., indicando che la conversazione contiene troppo pochi turni per essere riassunta; può accadere anche con un contesto completo, quando un singolo incolla di grandi dimensioni lo ha riempito.

Qui si confondono due costi. La richiesta di riepilogo condivide il prefisso, quindi legge la cache esistente invece di rielaborare la cronologia, e gran parte del tempo viene impiegata per generare il riepilogo. Compattare un contesto ampio resta comunque una richiesta ampia, perché la conversazione da riassumere è l'input. Il turno successivo al compattamento non è la parte lenta: ricostruisce la cache per un prompt molto più breve.

Esistono due comandi più economici. /rewind ripristina il codice e la conversazione a un checkpoint; per un percorso che vuoi abbandonare completamente è preferibile al compattamento, perché tronca la conversazione tornando a un prefisso già presente nella cache. /recap aggiunge un riepilogo come output del comando invece di sostituire la cronologia, quindi il prefisso memorizzato nella cache resta intatto.

Quando il compattamento automatico si attiva ripetutamente, viene stampato questo messaggio:

Autocompact is thrashing: the context refilled to the limit...

Il compattamento è riuscito, ma un file o l'output di uno strumento ha riempito più volte la finestra in sequenza, quindi Claude Code ha interrotto i nuovi tentativi. Per recuperare, leggi il file sovradimensionato per intervalli di righe, esegui /compact con un focus che escluda l'output di grandi dimensioni, sposta il lavoro a un subagent oppure usa /clear se la conversazione precedente è conclusa.

I server MCP comportano un overhead fisso

Ogni server MCP a cui ti connetti si aggiunge a ogni richiesta per l'intera sessione. Paghi il costo indipendentemente dal fatto che tu lo richiami o meno.

Claude Code attenua questo problema. Le definizioni degli strumenti MCP sono posticipate per impostazione predefinita, quindi solo i nomi degli strumenti entrano nel contesto finché Claude non utilizza uno strumento specifico. Esegui /context per vedere quanto costano realmente i tuoi server e /mcp disable <name> per rimuoverne uno che non userai oggi. Se gestisci i tuoi server MCP su una VPS, lo stesso calcolo limita il numero di strumenti che un singolo server dovrebbe esporre.

Esegui questa operazione all'inizio di una sessione. Mentre le definizioni rimangono posticipate, la connessione o la disconnessione di un server si limita ad aggiungere elementi alla conversazione e la cache rimane valida. Nei casi in cui le definizioni vengono caricate nel prefisso, perché la ricerca degli strumenti è disabilitata, non disponibile o al di sotto della soglia auto, la stessa modifica costringe la richiesta successiva a rileggere tutto.

Filtra l'output dettagliato degli strumenti prima che entri nel contesto

Il risultato di uno strumento è un input e viene reinviato a ogni turno successivo. Un'esecuzione di test che produce 20.000 token di output non ha un costo una tantum: paghi di nuovo per quell'output a ogni turno, finché non esce dalla finestra di contesto.

Filtra alla fonte. Un hook che riduce un'esecuzione di test ai soli errori prima che Claude la visualizzi trasforma quell'output molto esteso in poche centinaia di token, in questo turno e a ogni suo reinvio:

npm test 2>&1 | grep -E "FAIL|Error:" | head -40

Gli hook non entrano direttamente nel contesto, perché vengono eseguiti come codice. Applica questa tecnica a qualsiasi strumento il cui output superi una schermata. La stessa logica vale per un file di 3.000 righe: richiedi l'intervallo di righe necessario, perché l'intero file rimane nella finestra di contesto una volta ricevuto.

Definisci l’ambito dei file letti dall’agente e delega le attività rumorose

Un prompt che indica il file e il sintomo legge quel file. Una richiesta generica di riordinare il progetto porta l’agente a leggere tutti i file che ritiene pertinenti, e ogni lettura rimane nella finestra di contesto.

Delega le attività che producono molto output a un subagent. Le esecuzioni dei test e l’elaborazione dei log consumano entrambe contesto reale; un subagent mantiene quell’output nella propria finestra e restituisce solo un riepilogo. Il compromesso è il seguente: un subagent crea la propria cache, che alla prima chiamata non contiene hit, e utilizza la durata della cache di cinque minuti anche con un abbonamento. La delega protegge in modo affidabile il contesto principale. Non riduce sempre il numero totale di token.

Il clock della cache: lavorare a sessioni

Il prompt caching è ciò che rende conveniente il reinvio. La scrittura del prefisso costa 1,25 volte la tariffa di input base, o 2 volte se si considera la durata di un'ora. La lettura costa 0,1 volte su Haiku 5.5, 0,05 volte su Opus 5.5 e Sonnet 5.5 (rispettivamente 0,20 $ e 0,10 $ per milione di token) e 0,025 volte su Fable 5.1 (0,25 $ per milione). Ogni utilizzo aggiorna la voce senza costi aggiuntivi, quindi il clock riparte dall'ultimo utilizzo. Questi moltiplicatori indicano la struttura della fattura ma non il suo importo; incrociateli con quanto costa realmente un milione di token per convertire un'intera finestra di contesto in una cifra in dollari.

La durata ottenuta dipende dalla modalità di autenticazione, motivo per cui un'affermazione generica come "la cache scade dopo cinque minuti" è imprecisa.

• Con un abbonamento Claude, Claude Code richiede automaticamente la durata di un'ora.
• Una volta superato il limite del piano e iniziando a utilizzare i crediti di consumo, si viene fatturati per tale utilizzo, quindi la durata torna a cinque minuti.
• Con una API key o un provider cloud, la durata rimane di cinque minuti. Impostare promptCacheTtl su 1h, o ENABLE_PROMPT_CACHING_1H=1, abilita la durata di un'ora, mentre FORCE_PROMPT_CACHING_5M=1 la riporta al valore predefinito.

Il consiglio sul ritmo di lavoro è identico in entrambi i casi: lavorate in sessioni continue, poiché un periodo di inattività superiore alla durata della cache costringe il turno successivo a riscrivere l'intero prefisso accumulato. Una sessione di Claude Code distaccata in tmux non ha costi durante l'inattività, ma il tempo di inattività comporta la perdita della cache riscaldata.

Alcune azioni eliminano la cache mentre state ancora lavorando: cambiare modello, modificare il livello di sforzo sui modelli meno recenti, attivare la modalità rapida, connettere o disconnettere un server MCP o negare un intero strumento quando le definizioni degli strumenti vengono caricate all'avvio, abilitare o disabilitare un plugin che aggiunge strumenti, compattare, eliminare vecchie immagini quando una conversazione ne contiene troppe e aggiornare Claude Code. Su Opus 5.5, Sonnet 5.5, Haiku 5.5 e Fable 5.1 con una API key o un abbonamento, un cambio di sforzo ora mantiene la cache. /model è la sorpresa tipica, poiché ogni modello ha la propria cache; di conseguenza, la richiesta successiva legge l'intera cronologia senza hit della cache, anche se il contenuto è identico. Tale rilettura viene fatturata alle tariffe del modello di destinazione come una nuova scrittura in cache; pertanto, un cambio di modello verso Fable a metà sessione addebita l'intera cronologia accumulata alle tariffe di scrittura in cache pubblicate per Fable: 12,50 $ per milione di token con durata di cinque minuti o 20 $ per quella di un'ora, identiche su Fable 5 e Fable 5.1.

Modificare file, modificare CLAUDE.md, invocare skill e comandi, eseguire /recap, riavvolgere e generare un subagent sono tutte operazioni che mantengono la cache. L'ambito è limitato a una singola macchina e a una singola directory, quindi due sessioni in directory diverse non condividono la cache. Tale ambito segue la CLI anziché l'account, pertanto nulla viene trasferito all'app desktop di Claude, che su Linux è un'installazione beta separata a fianco della CLI.

Per verificare se la cache sta funzionando, leggete current_usage. cache_creation_input_tokens è stato scritto alla tariffa di scrittura in cache; cache_read_input_tokens è stato servito alla tariffa di lettura in cache del modello, tra il 2,5% e il 10% della tariffa di input standard a seconda del modello. Un rapporto elevato tra letture e creazioni è indice di un buon funzionamento. Se la creazione rimane alta turno dopo turno, significa che qualcosa nel prefisso continua a cambiare.

Una finestra di contesto più ampia risolve il problema?

In parte. Ogni modello attuale (Fable 5.1, Opus 5.5, Sonnet 5.5 e Haiku 5.5) utilizza una finestra di contesto da 1 milione di token e la compattazione funziona allo stesso modo anche al limite superiore. L'economia del sistema non cambia, poiché l'intero prompt viene comunque reinviato e fatturato a ogni turno. Una finestra più grande determina quando sei costretto ad agire; l'igiene dei dati determina il costo. Se il problema è la fattura piuttosto che il limite massimo, quale piano Claude si adatta al tuo modo di lavorare determina se stai spendendo dollari o il credito del piano.

Modifica del contesto e compattamento nell'API sono funzionalità diverse

Se stai creando un tuo agent sull'API Messages, non esistono comandi slash e devi implementare questa logica autonomamente. Prevedi questo lavoro fin dall'inizio, perché le quote gratuite dell'API non copriranno i costi dei tuoi token. I nuovi utenti ricevono una piccola quantità di crediti gratuiti per testare l'API, mentre la quota gratuita continuativa indicata da Anthropic (50 ore gratuite al giorno per organizzazione nella pagina dei prezzi, 1,550 al mese nella documentazione) copre il tempo dei container per l'esecuzione del codice, fatturato separatamente dai token. A ogni turno viene reinviata la cronologia non ridotta e tutto viene fatturato: alla tariffa di lettura della cache quando il prefisso è memorizzato, oppure alla tariffa completa dell'input o con un sovrapprezzo per la scrittura nella cache quando non lo è. Il provider su cui costruisci l'agent determina questo calcolo prima di qualsiasi riduzione, quindi, se la scelta è ancora aperta, calcola il costo dello stesso carico di lavoro su entrambe le API invece di confrontare le sole tariffe nominali per token. Due funzionalità lato server svolgono questo compito, ma non sono la stessa funzionalità.

La modifica del contesto cancella selettivamente contenuti specifici dalla cronologia della conversazione man mano che cresce e sostituisce ogni risultato cancellato con testo segnaposto, così Claude sa che qualcosa è stato rimosso. È una funzionalità beta: invia anthropic-beta: context-management-2025-06-27 e configura le strategie in context_management.edits. clear_tool_uses_20250919 cancella i risultati degli strumenti, mentre clear_thinking_20251015 gestisce i blocchi di ragionamento. Il valore predefinito di trigger è 100,000 token di input, quello di keep è costituito dagli ultimi 3 utilizzi degli strumenti e quello di clear_tool_inputs è false, quindi gli input restano e vengono rimossi soltanto i risultati.

Il compattamento genera un riepilogo e sostituisce con esso l'intera cronologia della conversazione. È disponibile in due modalità beta. Il compattamento basato sulla soglia viene eseguito all'interno delle normali richieste: invia anthropic-beta: compact-2026-01-12 e usa il tipo di modifica compact_20260112. Il valore predefinito del trigger è {"type": "input_tokens", "value": 150000} e il valore deve essere almeno 50,000. Con il compattamento su richiesta, è il tuo codice a decidere quando eseguirlo: invia anthropic-beta: compact-2026-09-04 con un "compaction": {"type": "summarize"} al livello superiore e la risposta contiene soltanto il blocco di riepilogo. La panoramica di Anthropic sul compattamento raccomanda di usare il compattamento su richiesta ovunque sia disponibile.

Il compattamento basato sulla soglia ha una regola di passaggio che può interrompere silenziosamente gli agent. La risposta inizia con un blocco di contenuto compaction che contiene il riepilogo, seguito dal normale blocco di testo. Devi reinviare quel blocco nelle richieste successive; l'API eliminerà quindi ogni blocco di contenuto precedente. In pratica, aggiungi l'intero contenuto di response.content, non soltanto il testo. Il compattamento su richiesta funziona al contrario: rimuovi autonomamente i messaggi riassunti, inserisci il blocco restituito all'inizio di messages e reinvialo esattamente come è stato restituito, inclusa la firma.

La documentazione di Anthropic definisce il compattamento lato server come la strategia principale per gestire il contesto nelle conversazioni di lunga durata, mentre la modifica del contesto è l'opzione per un controllo più preciso sui contenuti da cancellare. Verifica prima il supporto del modello. Tutti i modelli attuali supportano entrambi i tipi di compattamento, incluso Haiku 5.5; il modello precedente claude-haiku-4-5 non li supporta e ogni pagina relativa al compattamento contiene l'elenco aggiornato. Nessuna di queste funzionalità beta controlla il /compact di Claude Code, che la documentazione descrive come una richiesta di riepilogo distinta inviata dal client insieme alla cronologia.

FAQ

Perché la mia sessione di Claude Code diventa più lenta e costosa man mano che viene utilizzata?

Poiché l'intera conversazione viene inviata nuovamente a ogni turno, una domanda di una riga in una sessione aperta tutto il giorno trascina con sé l'intera giornata. Il prompt caching mantiene i costi contenuti finché la cache è attiva: una lettura costa 0.1x la tariffa base di input su Haiku 5.5, 0.05x su Opus 5.5 e Sonnet 5.5, e 0.025x su Fable 5.1. Quando un turno non trova riscontro nella cache, lo stesso prefisso viene riscritto a 1.25x, o 2x se supera l'ora di vita. Esegui /context per vedere cosa sta riempiendo la finestra di contesto e leggi cosa ti viene addebitato in una sessione di Claude Code per comprendere il meccanismo.

Qual è la differenza tra /clear e /compact in Claude Code?

/clear avvia una nuova conversazione con contesto vuoto. Non invia alcuna richiesta, quindi non ha costi ed è la scelta corretta tra attività non correlate. /compact mantiene la stessa conversazione e sostituisce la cronologia con un riepilogo, quindi è la scelta corretta all'interno di una singola attività lunga. Fornisci un focus, come in /compact keep only the plan and the diff, poiché l'istruzione determina cosa viene conservato.

Come posso vedere cosa sta occupando la mia finestra di contesto di Claude Code?

Esegui /context, oppure /context all per il dettaglio completo per singolo elemento. Mostra il system prompt, le definizioni dei tool, i server MCP, i file di memoria e la cronologia sotto forma di griglia colorata, con suggerimenti per i tool che pesano sul contesto e per l'eccesso di memoria. Con un piano a pagamento, /usage attribuisce anche l'utilizzo recente a singole competenze, subagenti e server MCP.

Dovrei usare una finestra di contesto da 1 milione di token invece di compattare?

Una finestra più ampia ritarda il problema invece di risolverlo. Ogni modello attuale (Fable 5.1, Opus 5.5, Sonnet 5.5 e Haiku 5.5) gestisce una finestra di contesto da 1 milione di token e la compattazione si comporta allo stesso modo. Ogni turno continua a inviare l'intero prompt e a fatturarlo, quindi una conversazione da 400.000 token è costosa a prescindere dal fatto che rientri o meno nei limiti.

Qual è la differenza tra context editing e compattazione nella Claude API?

Il context editing cancella selettivamente i vecchi contenuti, principalmente i risultati dei tool, lasciando un testo segnaposto dove si trovavano in modo che Claude sappia che sono stati rimossi. La compattazione genera un riepilogo e sostituisce l'intera cronologia con esso. La documentazione di Anthropic definisce la compattazione come la strategia principale per le conversazioni a lunga durata e posiziona il context editing come l'opzione più granulare. Entrambi sono in versione beta con i propri header e sono separati da /compact di Claude Code.