Le finestre di contesto sono passate da poche migliaia a centinaia di migliaia di token, in alcuni modelli oltre il milione. Sembrerebbe un problema risolto: si mette tutto nel prompt e il modello trova ciò che serve. Chi lavora ogni giorno con gli agenti sa che non è così. Dopo un’ora di sessione l’agente dimentica le istruzioni iniziali, ripete errori già corretti, si confonde tra versioni diverse dello stesso file.
Questo fenomeno ha un nome, context rot, e la disciplina che lo affronta si chiama context engineering. Il 20 ottobre DeepLearning.AI ha lanciato un corso dedicato insieme a Chroma, il team che ha misurato il problema per primo. Nello stesso mese IndyDevDan ha costruito un agente che decide da solo quando compattare il proprio contesto e Cole Medin ha mostrato quanti token si sprecano solo per cercare il codice giusto.
Questa guida spiega cosa succede quando il contesto si riempie, quali errori lo peggiorano e quali tecniche usare nei tuoi agenti, dalla sessione di coding all’agente in produzione.
Per un’azienda il context rot non è un dettaglio da sviluppatori. È spesso la ragione per cui un assistente AI che funzionava bene in una demo inizia a dare risposte sbagliate quando viene collegato a manuali, listini, CRM e archivi reali. E il contesto è anche la voce che pesa di più sui costi dei modelli.
In breve
- Il context engineering è la progettazione di tutto ciò che il modello vede prima di rispondere: istruzioni, documenti, risultati degli strumenti, cronologia, memoria.
- Il context rot è il calo di affidabilità dei modelli quando il contesto cresce, anche su compiti semplici e ben sotto il limite della finestra.
- Il contesto va trattato come un budget: l’obiettivo è il più piccolo insieme di informazioni ad alto segnale.
- Le tecniche principali sono: recupero mirato, caricamento progressivo, compattazione, note strutturate esterne, subagent con contesto isolato e pulizia dei risultati degli strumenti.
- Negli agenti di coding la maggior parte dei token si consuma nella ricerca del codice, non nella scrittura.
- Una sessione nuova con un buon riepilogo spesso funziona meglio di una sessione lunga.
- Per chi decide: la qualità di un assistente AI aziendale dipende più da quali informazioni riceve che dal modello scelto. Investire nella selezione e nell’ordine dei contenuti costa meno che passare a un modello più caro.
Che cos’è il context engineering
Il context engineering è la progettazione delle informazioni che arrivano al modello a ogni passo: cosa includere, in quale formato, in che ordine e soprattutto cosa lasciare fuori. Il termine è stato reso popolare a metà 2025 da Andrej Karpathy, che in un post molto citato lo descriveva come l’arte di riempire la finestra di contesto con esattamente le informazioni giuste per il passo successivo.
Per un chatbot il contesto è quasi solo la conversazione. Per un agente è molto di più:
- istruzioni di sistema e file di progetto come AGENTS.md o CLAUDE.md;
- definizioni degli strumenti disponibili, spesso decine;
- risultati degli strumenti: file letti, output di comandi, pagine web, risposte di API;
- cronologia dei passi precedenti, inclusi tentativi falliti;
- memoria recuperata da sessioni passate o da una base di conoscenza.
Ogni elemento occupa spazio e attenzione. Il prompt engineering si occupa di come formulare una richiesta; il context engineering si occupa dell’intero ambiente informativo in cui la richiesta viene elaborata, e di come cambia passo dopo passo. Nel nostro articolo sull’harness engineering abbiamo visto che il contesto è uno dei componenti dell’harness: qui entriamo nel dettaglio.
Cosa significa per un’azienda
Il context engineering ha conseguenze dirette su qualità, costi e governance dei progetti AI aziendali. Ecco le più importanti.
Il caso tipico: l’assistente che peggiora con più documenti
Un’azienda collega il proprio assistente AI a tutta la documentazione interna: manuali, procedure, listini, presentazioni. Le prime risposte sono buone, poi iniziano gli errori: prezzi del listino dell’anno scorso, procedure superate, informazioni contraddittorie. Il modello non è peggiorato. Il contesto è pieno di documenti simili ma non aggiornati, cioè proprio i distrattori che lo studio di Chroma indica come la causa principale del calo di qualità.
La qualità dei documenti diventa un prerequisito
Un progetto AI è spesso la prima occasione per scoprire quanto è disordinata la documentazione aziendale: versioni duplicate, documenti senza data, informazioni che esistono solo nelle email. Riordinare le fonti, indicare una fonte di verità per ogni argomento e archiviare ciò che è superato migliora le risposte più di qualsiasi tecnica sofisticata.
Il contesto è la bolletta
Ogni token di contesto si paga a ogni richiesta. Un assistente che per rispondere carica cinquanta pagine costa molte volte uno che ne carica tre, e spesso risponde peggio. Quando un fornitore propone un sistema AI, chiedere quanto contesto viene usato per una domanda tipica dà un’idea immediata sia della qualità sia dei costi futuri.
Chi decide cosa entra nel contesto
Non è solo una scelta tecnica. Quali documenti può consultare l’assistente? Può vedere dati dei clienti? Contratti? Informazioni riservate sul personale? Serve una persona responsabile, di solito d’intesa con chi si occupa di privacy, che decida le fonti ammesse e le riveda periodicamente.
Domande da fare a chi sviluppa il sistema
- Quali documenti vengono recuperati per rispondere a una domanda, e come vengono scelti?
- Come gestite le versioni superate dei documenti?
- Quanto contesto usa in media una richiesta, e quanto costa?
- Come misurate la qualità delle risposte, su quali domande di prova?
- Quali dati personali possono entrare nel contesto, e con quali garanzie?
Il context rot: cosa succede quando il contesto cresce
Nel 2025 il team di ricerca di Chroma ha pubblicato lo studio Context Rot, testando 18 modelli di punta su compiti volutamente semplici. Il risultato: le prestazioni calano in modo misurabile all’aumentare della lunghezza dell’input, anche quando il compito non diventa più difficile e la finestra è lontana dal limite.
Lo studio ha messo in evidenza alcuni fattori che peggiorano il calo:
- Distrattori: informazioni simili a quella cercata ma non corrette confondono il modello molto più del semplice rumore.
- Bassa somiglianza tra domanda e risposta: se l’informazione utile è espressa con parole diverse dalla domanda, il modello fatica di più a trovarla in un contesto lungo.
- Struttura del testo: in modo controintuitivo, testi coerenti e ben organizzati possono rendere più difficile individuare un dettaglio rispetto a frammenti sparsi.
Il problema non è nuovo. Già nel 2023 il paper Lost in the Middle aveva mostrato che i modelli usano meglio le informazioni all’inizio e alla fine del contesto rispetto a quelle nel mezzo. I modelli sono migliorati, ma la regola di fondo resta: l’attenzione è una risorsa limitata, e ogni token in più la divide.
Anche Anthropic, nella guida Effective context engineering for AI agents, descrive il contesto come una risorsa finita con rendimenti decrescenti e indica come obiettivo il più piccolo insieme possibile di token ad alto segnale.
I quattro modi in cui il contesto fallisce
Drew Breunig, che ha collaborato al corso di DeepLearning.AI, ha classificato i fallimenti più comuni in un articolo diventato un riferimento, How Long Contexts Fail. Li riprendiamo con esempi tratti dagli agenti di coding.
| Fallimento | Cosa succede | Esempio in un agente di coding |
|---|---|---|
| Avvelenamento (poisoning) | Un errore o un’allucinazione entra nel contesto e viene ripresa nei passi successivi | L’agente inventa il nome di una funzione, poi continua a chiamarla in ogni file |
| Distrazione | Il contesto è così lungo che il modello si concentra sulla cronologia invece che sul compito | Dopo 50 passi ripete strategie già provate invece di cercarne di nuove |
| Confusione | Informazioni superflue, come troppi strumenti, influenzano la risposta | Con 80 strumenti MCP caricati sceglie quello sbagliato per un compito banale |
| Conflitto (clash) | Informazioni contraddittorie convivono nel contesto | Ha letto due versioni dello stesso file e mescola codice vecchio e nuovo |
Riconoscere il tipo di fallimento aiuta a scegliere la correzione. L’avvelenamento si cura ripartendo da un contesto pulito; la confusione riducendo gli strumenti; il conflitto eliminando le versioni obsolete.
Il contesto come budget
Il cambio di mentalità più utile è smettere di chiedersi “c’è spazio?” e iniziare a chiedersi “questo token vale la sua attenzione?”. Proviamo a fare i conti di una sessione tipica di un agente di coding.
- Istruzioni di sistema dell’agente: alcune migliaia di token, fisse.
- Definizioni degli strumenti: da poche migliaia a decine di migliaia se si collegano molti server MCP.
- File di progetto (AGENTS.md, CLAUDE.md): da poche centinaia a diverse migliaia.
- File letti per capire il codice: spesso la voce più grande, decine di migliaia di token.
- Output di comandi e test: possono esplodere con log lunghi o stack trace.
Cole Medin, nel video Your Coding Agent Wastes SO MANY Tokens Just Finding Code, sottolinea un punto che molti trascurano: la maggior parte di ciò che paghiamo a un agente non è la scrittura del codice, ma la ricerca del codice da modificare. La ricerca è veloce, ma leggere interi file per capire quali contano consuma contesto prima ancora di iniziare.
In Claude Code il comando /context mostra come è distribuito il contesto della sessione corrente. Guardarlo ogni tanto è il modo più rapido per accorgersi che metà della finestra è occupata da strumenti che non stai usando. La pagina sulla gestione dei costi della documentazione elenca le leve principali per ridurre il consumo.
Le tecniche che funzionano
Breunig, nel seguito How to Fix Your Context, e Anthropic nella sua guida convergono su un insieme di tecniche. Le presentiamo in ordine di semplicità.
1. Recupero mirato invece di caricamento in blocco
Invece di inserire tutta la documentazione o tutto il codice, l’agente recupera solo i frammenti pertinenti al passo corrente. Negli agenti di coding questo significa cercare con strumenti come grep o un indice del codice e leggere solo le porzioni utili dei file, non i file interi.
2. Caricamento progressivo
Le informazioni vengono rivelate a livelli: prima un indice o una descrizione breve, poi il dettaglio solo se serve. Le skill di Claude Code funzionano così: nel contesto c’è solo una riga di descrizione per ciascuna, e il contenuto completo viene caricato quando l’agente decide di usarla. Lo stesso principio vale per la documentazione interna: un indice con link è meglio di un documento unico da cinquanta pagine.
3. Selezione degli strumenti
Ogni strumento disponibile occupa contesto con nome, descrizione e schema dei parametri, e aumenta il rischio di confusione. Collega solo i server MCP che servono per il progetto, e valuta di disattivare quelli che usi raramente. Per sistemi con molti strumenti, una fase di preselezione (anche con un modello decisionale) riduce l’elenco a quelli pertinenti.
4. Pulizia dei risultati degli strumenti
Un comando che restituisce diecimila righe di log non deve finire intero nel contesto. Gli strumenti ben progettati restituiscono riepiloghi, troncano gli output lunghi e indicano dove trovare il resto. Se scrivi script per il tuo harness, falli parlare poco: “3 test falliti: nomi e prime righe dell’errore” vale più dell’output completo.
5. Compattazione
Quando il contesto si avvicina al limite, la cronologia viene riassunta e la sessione prosegue dal riassunto. La maggior parte degli agenti lo fa automaticamente a una soglia fissa. IndyDevDan contesta questo approccio nel video Self-Compact Pi Agent: un agente sa meglio di una percentuale fissa quando ha finito una fase di lavoro ed è il momento giusto per compattare. Il codice è disponibile nel repository self-compact-pi-agent.
In pratica, anche senza costruire un agente personalizzato, puoi applicare lo stesso principio a mano: compatta o riparti alla fine di una fase logica (dopo aver chiuso un task, prima di iniziarne un altro), non nel mezzo di un ragionamento.
6. Note strutturate esterne
L’agente scrive i progressi in un file esterno al contesto: cosa ha fatto, cosa resta, quali decisioni ha preso. Nella sessione successiva legge il file invece di dipendere da una cronologia lunga. Anthropic usa questo schema per gli agenti che lavorano per molte ore, con un file di avanzamento e un elenco di funzionalità in JSON.
7. Subagent con contesto isolato
Un subagent riceve un compito, lavora in un proprio contesto separato e restituisce all’agente principale solo un riepilogo. È la tecnica più efficace per le esplorazioni: “trova tutti i punti in cui calcoliamo l’IVA” può richiedere la lettura di decine di file, ma all’agente principale arriva solo l’elenco finale. La documentazione sui subagent di Claude Code spiega come definirli.
8. Ripartire da zero
La tecnica più sottovalutata. Quando una sessione è avvelenata o confusa, continuare a correggerla costa più che ricominciare. Fatti scrivere un riepilogo dello stato, chiudi la sessione, aprine una nuova con il riepilogo. In Claude Code il comando /clear serve proprio a questo.
Context engineering negli agenti di coding: un flusso pratico
Ecco come mettiamo insieme le tecniche in una giornata di lavoro con un agente di coding.
- Una sessione per task. Ogni task (una funzionalità, un bug) ha la sua sessione. Quando il task è chiuso, la sessione si chiude.
- Esplorazione delegata. Le domande del tipo “dove si trova”, “come funziona”, “chi chiama” vanno a un subagent. All’agente principale arrivano solo le conclusioni.
- Piano scritto. Prima di modificare il codice, l’agente scrive un piano breve in un file. Se la sessione va storta, il piano sopravvive.
- Output dei test filtrati. Lo script di test restituisce solo i fallimenti, con le prime righe dell’errore.
- Checkpoint a fine fase. Alla fine di ogni fase logica si aggiorna il file di avanzamento; se il contesto è pesante si compatta o si riparte.
# progress.md (aggiornato dall'agente a fine fase)
## Obiettivo
Filtro per stato nella pagina /ordini (ticket #482)
## Fatto
- Endpoint GET /api/ordini accetta ?stato= (test: ordini.test.ts)
- Componente FiltroStato creato, non ancora collegato
## Decisioni
- Gli stati arrivano da enum OrdineStato, non da stringhe libere
## Prossimo passo
- Collegare FiltroStato alla tabella e aggiungere test e2eUn file così occupa poche centinaia di token e sostituisce decine di migliaia di token di cronologia.
Context engineering negli agenti in produzione
Negli agenti che servono clienti o automatizzano processi il problema si presenta in modo diverso: le conversazioni sono più brevi, ma i dati arrivano da fonti esterne e la memoria persiste tra sessioni.
Memoria a lungo termine
Salvare tutto non è memoria, è accumulo. Una buona memoria distingue tra fatti stabili (preferenze del cliente, contratto in essere), informazioni temporanee (lo stato di un ordine) e dettagli da dimenticare. DeepLearning.AI ha dedicato un corso breve proprio a questo tema, con memoria che resta sul dispositivo: Building AI Assistants with On-Device Memory.
Recupero da fonti multiple
Quando l’agente cerca in documentazione, CRM e ticket, i risultati possono contraddirsi. Conviene indicare nel contesto la fonte e la data di ogni frammento, così il modello può preferire l’informazione più recente o più autorevole invece di mescolarle.
Valutazione con le tracce
Il corso Context Engineering di DeepLearning.AI, presentato nel video Learn to build better AI Agents through better context, insiste su un punto: usare le tracce delle esecuzioni reali per capire quali strumenti l’agente sceglie e perché, e migliorare la selezione con valutazioni misurabili. Senza tracce, il context engineering resta un’opinione.
Errori comuni
“Tanto la finestra è da un milione di token”
La dimensione massima della finestra non dice nulla sulla qualità delle risposte quando è piena. Il context rot si manifesta molto prima del limite.
Un file di istruzioni che cresce senza controllo
Ogni regola aggiunta per correggere un errore occupa contesto in tutte le sessioni future. Dopo qualche mese il file è lungo, contraddittorio e diluisce le istruzioni importanti.
Troppi server MCP collegati
Collegare tutti gli strumenti disponibili “perché potrebbero servire” è la causa più comune di confusione. Gli strumenti vanno collegati per progetto, non per abitudine.
Correggere una sessione avvelenata invece di ripartire
Se l’agente insiste su un’ipotesi sbagliata, ogni correzione aggiunge altro testo sull’ipotesi sbagliata. Ripartire con un riepilogo pulito è quasi sempre più rapido.
Compattare nel momento sbagliato
Una compattazione automatica a metà di un debug complesso può perdere proprio i dettagli che servivano. Quando possibile, scegli tu il momento.
Output degli strumenti non filtrati
Un singolo comando con un log enorme può occupare più contesto di tutto il resto della sessione. Filtra a monte.
Portarlo in produzione
Quando il context engineering diventa parte di un prodotto, servono alcune scelte di progetto.
- Misura il contesto: registra quanti token occupa ogni componente (istruzioni, strumenti, recupero, cronologia) in ogni chiamata. È il primo dato da guardare quando la qualità cala o i costi crescono.
- Definisci limiti espliciti: un numero massimo di frammenti recuperati, una lunghezza massima per gli output degli strumenti, una soglia oltre la quale si riassume la cronologia.
- Versiona le istruzioni: prompt di sistema, descrizioni degli strumenti e template di contesto sono codice. Vanno versionati e testati come tale.
- Valuta su casi reali: costruisci un set di conversazioni o task rappresentativi e misura la qualità prima e dopo ogni modifica al contesto.
- Attenzione ai dati personali: tutto ciò che entra nel contesto viene inviato al fornitore del modello. Recupera solo i dati necessari e pseudonimizza dove possibile.
Il tuo agente funziona bene nei test ma peggiora con l’uso reale? Spesso il problema è il contesto. Nella nostra consulenza AI analizziamo tracce e costi e ridisegniamo il flusso di informazioni; se l’agente è parte di una web app, interveniamo anche sull’architettura.
Da dove partire questa settimana
- Apri una sessione tipica del tuo agente e guarda come è distribuito il contesto (in Claude Code con
/context). - Scollega i server MCP e gli strumenti che non hai usato nell’ultima settimana.
- Accorcia il file di istruzioni del progetto: sposta le procedure specifiche in skill caricate al bisogno.
- Adotta la regola “una sessione per task” e un file di avanzamento per i task lunghi.
- Delega le esplorazioni del codice a un subagent e confronta il consumo di token con la settimana precedente.
Checklist di context engineering
- Sai quanti token occupano istruzioni, strumenti, recupero e cronologia.
- Sono collegati solo gli strumenti utili al progetto corrente.
- Le istruzioni fisse sono brevi; le procedure sono caricate al bisogno.
- Gli output di comandi e test sono filtrati prima di entrare nel contesto.
- Le esplorazioni ampie avvengono in subagent con contesto isolato.
- I task lunghi hanno un file di avanzamento aggiornato a fine fase.
- Le sessioni vengono chiuse alla fine di ogni task.
- Le informazioni recuperate riportano fonte e data.
- Esiste un set di casi reali per valutare le modifiche al contesto.
- Nel contesto entrano solo i dati personali strettamente necessari.
Domande frequenti
Che cos’è il context rot in parole semplici?
È il peggioramento delle risposte di un modello quando il testo che riceve diventa lungo. Anche se l’informazione giusta è presente, il modello fatica a trovarla e usarla correttamente tra tutte le altre. Il calo si vede ben prima del limite massimo della finestra di contesto.
Context engineering e prompt engineering sono la stessa cosa?
No. Il prompt engineering riguarda come formulare una singola richiesta. Il context engineering riguarda tutto ciò che il modello vede a ogni passo: istruzioni, strumenti, documenti recuperati, cronologia e memoria, e come queste informazioni cambiano durante il lavoro di un agente.
Conviene usare modelli con finestre di contesto più grandi?
Una finestra grande è utile come margine, ma non va riempita. Le prestazioni migliori si ottengono con contesti piccoli e pertinenti. Una finestra ampia permette di gestire casi eccezionali senza errori, non di smettere di selezionare le informazioni.
Quando devo compattare o ripartire con una nuova sessione?
Alla fine di una fase logica di lavoro, quando il contesto è pesante, oppure subito se l’agente ripete errori o insiste su ipotesi sbagliate. In questi casi un riepilogo scritto e una sessione nuova sono più efficaci che continuare a correggere.
I subagent fanno risparmiare token?
Spesso fanno risparmiare contesto all’agente principale, che è la risorsa più preziosa. Il consumo totale di token può essere simile o persino maggiore, perché il subagent lavora in parallelo. Il vantaggio è la qualità: l’agente principale ragiona su un contesto pulito.
Come capisco se il mio agente soffre di context rot?
I segnali tipici sono: istruzioni iniziali ignorate dopo molti passi, errori già corretti che ritornano, confusione tra versioni dello stesso file, scelta di strumenti sbagliati. Se la qualità migliora ripartendo con una sessione nuova, il problema era il contesto.
Perché il nostro assistente AI risponde peggio da quando gli abbiamo dato più documenti?
Probabilmente per il context rot: più documenti simili, obsoleti o contraddittori rendono più difficile per il modello trovare l’informazione giusta. La soluzione è selezionare le fonti, eliminare o archiviare le versioni superate e recuperare per ogni domanda solo i pochi contenuti davvero pertinenti.
Fonti e approfondimenti
- Chroma Research: Context Rot
- Anthropic: Effective context engineering for AI agents
- Drew Breunig: How Long Contexts Fail
- Liu et al.: Lost in the Middle (arXiv)
- LangChain: Context engineering for agents
- DeepLearning.AI: corso Context Engineering
Vuoi agenti che restano lucidi anche dopo ore di lavoro? Raccontaci cosa vuoi fare e analizziamo insieme come il tuo sistema usa il contesto.