Finestra di contesto dell'agente LLM: che cosa ci finisce dentro e perché l'agente dimentica le regole

Che cos'è la finestra di contesto di un LLM

La finestra di contesto di un LLM è tutto il testo che il modello riceve in input quando genera la risposta successiva. Il modello non ha memoria nel senso umano: tutto ciò che «sa» del vostro compito in quel momento sta in questa finestra. Ciò che non c'è nella finestra, per il modello non esiste.

La dimensione della finestra si misura in token — frammenti di parole. Per il testo italiano, come per quello russo, un token in media è più corto che per l'inglese, quindi la stessa istruzione costa di solito più token. Le finestre dei modelli attuali arrivano a centinaia di migliaia di token e sembra che lo spazio basti per tutto. In pratica, però, lo spazio di un agente finisce più in fretta di quanto si pensi, e il suo rendimento comincia a calare ancora prima.

Che cosa finisce nella finestra di contesto dell'agente

Un agente per la programmazione riceve informazioni da tre sole fonti: il prompt di sistema con la descrizione del compito, il contenuto dei file che ha letto e l'output degli strumenti che ha chiamato. Tutte e tre vivono nella stessa finestra e competono per lo spazio.

Il punto chiave: nulla di tutto questo scompare da solo. Il log dei test caduti, che serviva venti passi fa, resta nella finestra e sottrae attenzione al passo attuale. Una sessione lunga è un mucchio che cresce continuamente, in cui è sempre più difficile trovare l'ago.

Perché l'agente dimentica le regole in una sessione lunga

Lamentela frequente: all'inizio della sessione l'agente rispetta con attenzione le regole del CLAUDE.md, ma dopo un'ora di lavoro comincia a violarle. In senso letterale non le ha «dimenticate» — il testo delle regole è ancora nella finestra. Il problema è come il modello distribuisce l'attenzione su un testo lungo.

Lost in the middle

Uno studio di Liu e coautori del 2023 ha mostrato che i modelli linguistici usano in modo sensibilmente migliore le informazioni dell'inizio e della fine di un contesto lungo, rispetto a quelle del mezzo. Il file delle istruzioni viene caricato all'inizio della sessione, ma man mano che il dialogo procede si accumula sempre più testo sopra e sotto di esso. La regola che era in evidenza finisce gradualmente nella zona dove il modello «vede» peggio.

La quota delle regole nella finestra cala

In una sessione nuova le istruzioni sono una parte consistente del contesto. Dopo un centinaio di chiamate agli strumenti diventano un piccolo frammento sullo sfondo di log, diff e codice letto. Il segnale è lo stesso, ma il rumore intorno è decine di volte più grande.

Gli esempi recenti pesano più delle vecchie regole

Il modello si appoggia molto a ciò che è successo di recente nel dialogo. Se l'agente ha più volte fatto qualcosa aggirando una regola e l'ha passata liscia, questo schema nella cronologia comincia a pesare più di una riga di istruzione da qualche parte all'inizio.

Context rot: il degrado della qualità prima del limite della finestra

Context rot («marcescenza del contesto») è l'effetto per cui la qualità delle risposte del modello cala man mano che la finestra si riempie, anche se il limite tecnico è ancora lontano. Il modello formalmente accetta 200 mila token, ma con 150 mila lavora peggio che con 20 mila: sbaglia più spesso i dettagli, ripropone soluzioni già scartate, perde le istruzioni.

Segnali che la sessione è «marcita»:

• l'agente propone un approccio da cui avete insieme rinunciato mezz'ora fa;
• confonde nomi di file e funzioni già discussi;
• smette di lanciare i controlli che all'inizio lanciava da sé;
• le risposte diventano più lunghe e vaghe, compaiono «già che c'ero ho sistemato anche…» superflui.

Curare tutto questo aggiungendo un'altra regola non serve: anche la nuova regola si perderà nello stesso rumore. Bisogna ridurre il rumore.

La compattazione del contesto

La compattazione è la compressione della storia della sessione: il modello scrive una sintesi di ciò che è accaduto, e il dialogo prosegue con questa sintesi al posto della cronologia completa. La finestra si libera, e il senso del lavoro sembra conservarsi.

In Claude Code per questo esiste il comando /compact, al quale si può passare un suggerimento su che cosa mantenere durante la compressione. Quando la finestra si avvicina al limite, Claude Code esegue la compattazione anche automaticamente. Il comando /clear cancella del tutto la cronologia e riparte da zero, mentre /context mostra come è occupata la finestra.

/context
/compact conserva: obiettivo del compito, decisioni prese con le motivazioni, elenco dei file modificati, che cosa resta da verificare
/clear

Che cosa c'è di pericoloso nella compattazione

Un riassunto perde sempre dei dettagli. Nella sintesi potrebbe non finire la variante scartata con il motivo del rifiuto, la formulazione esatta di un requisito o una sfumatura su cui vi siete accordati di passaggio. Dopo la compattazione l'agente lavora con il riassunto della propria stessa sessione, scritto da altri. Perciò le cose importanti conviene tenerle non nella cronologia del dialogo, ma in file che sopravvivono a qualsiasi compattazione.

Compattare o aprire una sessione nuova

Come risparmiare la finestra di contesto

Risparmiare contesto non riguarda il prezzo dei token, ma la qualità del lavoro. Meno rumore nella finestra significa più attenzione per il compito e per le regole.

1. Un file di istruzioni breve, come router

Il CLAUDE.md o AGENTS.md di ingresso viene letto per intero in ogni sessione. Un file da 600 righe equivale a circa 10–20 mila token di costo fisso. Teneteci i comandi di verifica, i vincoli assoluti e la mappa del progetto, e mettete i dettagli per tema in documenti separati che l'agente apre solo quando serve.

2. Conoscenze caricate su richiesta

Le skill di Claude Code sono costruite in modo che nel contesto finisca prima di tutto la loro breve descrizione, mentre il testo completo dell'istruzione si carica quando la skill serve al compito. È un modo comodo per tenere a portata di mano le procedure rare — deploy, migrazioni, rilascio — senza pagarle in ogni sessione.

3. Subagenti per il lavoro rumoroso

Un subagente lavora nella propria finestra di contesto e restituisce alla sessione principale solo il risultato. La ricerca in un codice grande, l'analisi di un log lungo, lo studio di un modulo sconosciuto: tutto questo si può affidare a un subagente e ricevere in cambio qualche paragrafo di conclusioni invece di migliaia di righe di output grezzo.

4. Output silenzioso degli strumenti

L'output dei comandi è il principale divoratore della finestra. Configurate i comandi di verifica in modo che, in caso di successo, stampino una sola riga, e in caso di errore solo l'essenziale: il test caduto e il suo messaggio, non il log completo della build.

# rumoroso: migliaia di righe nella finestra a ogni esecuzione
pytest -v

# silenzioso: in caso di successo una riga, in caso di caduta solo i test falliti
pytest -q --tb=short

# un log non per intero, ma solo la coda e gli errori
tail -n 50 app.log | grep -i error

5. Un compito, una sessione

Non trascinate una sessione attraverso tre compiti non correlati. La storia del primo compito non serve al terzo, ma occupa spazio e confonde l'agente. Finito il lavoro, fissate il risultato, poi aprite una sessione nuova.

6. Lo stato nei file, non nella cronologia

Tutto ciò che deve sopravvivere alla compattazione e alla sessione nuova va scritto nel repository: obiettivo, decisioni con le motivazioni, varianti scartate, che cosa è stato fatto e come è stato verificato, il passo successivo. Per esempio in PLAN.md e PROGRESS.md. Così la sessione nuova non comincia con un riassunto, ma con un documento preciso, e potete pulire la cronologia senza timori.

# PROGRESS.md
## Obiettivo
Portare il calcolo degli sconti a centesimi interi

## Fatto (verificato)
- app/payments/discount.py: float → int, make test verde
- Migrazione 041 aggiunta, applicata in locale

## Decisioni
- Arrotondamento bancario, come quello del provider di pagamento

## Scartato
- Decimal nel modello: rompe la serializzazione dei webhook

## Passo successivo
Aggiornare lo scenario e2e della procedura d'ordine ed eseguire make e2e

Le regole critiche non stanno solo nella finestra

Anche un contesto costruito in modo perfetto non garantisce il rispetto delle regole: il testo nella finestra è un'influenza sul modello, non un divieto eseguibile. Se una violazione è inaccettabile, la regola va verificata in modo meccanico. In Claude Code per questo ci sono gli hook — comandi che si avviano sugli eventi dell'agente e possono bloccare un'azione — e le impostazioni dei permessi, che vietano determinati strumenti o comandi. Linter, test e CI funzionano indipendentemente da ciò che succede in quel momento nella finestra dell'agente.

Buona regola dell'harness: tutto ciò che si può verificare automaticamente si verifica automaticamente, e nel contesto resta solo ciò che richiede giudizio.

Riepilogo

La finestra di contesto di un LLM è l'unico luogo in cui l'agente vede il vostro compito, e si riempie più in fretta di quanto sembri: istruzioni, cronologia, file letti e output dei comandi si accumulano fino alla fine della sessione. La qualità cala molto prima del limite tecnico, le regole dal mezzo di un contesto lungo si perdono, e la compattazione salva lo spazio al prezzo dei dettagli. Tenete le istruzioni brevi, caricate le conoscenze rare su richiesta, affidate il lavoro rumoroso ai subagenti, conservate lo stato nei file e rafforzate le regole critiche con hook e controlli. Il lavoro con il contesto dell'agente lo affrontiamo in pratica nel corso di harness engineering.