Ogni sessione parte da zero. Il mio agente riceve una mappa

Un sistema di gestione del contesto è un insieme di file di testo semplice, versionati nel repo, che mette in mano a un agente AI appena avviato una mappa: cosa leggere per primo, dove vive la verità attuale, quali decisioni sono chiuse. Il mio è passato per diverse ricostruzioni. Questa è la versione che è sopravvissuta, costi misurati inclusi.

Che cos’è un sistema di gestione del contesto?

Un insieme di file che dice all’agente dove guardare invece di costringerlo a cercare: un file di istruzioni che ogni sessione carica da sola, e che punta ai pochi documenti che dicono cosa è vero adesso, cosa è stato deciso e perché, e dove vive il codice di ogni area.

La condizione di partenza per cui esiste sta scritta nella documentazione stessa di Claude Code: “Ogni sessione di Claude Code comincia con una finestra di contesto nuova” [1]. Ogni sessione è un neoassunto con l’amnesia. Capace, ma uno che il tuo repo non l’ha mai visto e non ricorderà mai di averlo visto.

Il paragone a cui torno sempre è Google Maps. Quando chiedo una modifica alla fatturazione in un repo mappato, la prima lettura instrada l’agente: il file di regole punta a un indice, l’indice ha una riga per la fatturazione, la riga nomina due documenti e una cartella. Ci va. Senza la mappa fa grep, apre quello che combacia e assembla la sua immagine del sistema dai cinque file che gli sono capitati davanti per primi.

Quell’immagine è il prodotto. Tutto quello che l’agente fa dopo la eredita.

Quanto costa davvero una sessione da zero?

Due cose: qualità e token. Un agente che si orienta a colpi di parole chiave capisce il sistema troppo in superficie e consegna modifiche plausibili ma sbagliate. E l’orientamento stesso brucia la finestra di contesto prima che il lavoro vero cominci, e si scopre che è la metà più costosa.

Il contesto non è una risorsa piatta da spendere a piacere. Chroma Research ha valutato 18 modelli e ha trovato che le prestazioni degradano al crescere dell’input, anche su compiti che un prompt corto risolve senza fatica [2]. Drew Breunig ha catalogato i modi in cui fallisce: contesti che si avvelenano con errori precedenti, che spingono il modello a ripetere azioni passate o che si contraddicono al loro interno; cita uno studio Databricks in cui la correttezza inizia a calare verso i 32.000 token su Llama 3.1 405B, e agenti che degradano oltre i 100.000 token su modelli con finestre da un milione [3]. Il team di ingegneria di Anthropic chiama il budget col suo nome, attenzione: ogni token speso a orientarsi è attenzione che il modello non ha più per la modifica che gli hai chiesto [4].

Il mio repo principale rende concreta l’aritmetica. Il suo corpus di documentazione sono 418 file markdown, circa 7 MB di testo. Leggerlo tutto costerebbe tra 5,7 e 8,75 volte una finestra di contesto da 200.000 token, a seconda del metodo di stima. Non ci sta, e nessuna roadmap di modelli lo fa starci con eleganza. Quindi la domanda non è mai stata se l’agente legge un sottoinsieme. È chi sceglie il sottoinsieme: l’agente, affidandosi alla fortuna del grep, o io, per progetto.

Quattro livelli e una frase

Il sistema su cui sono atterrato sono quattro livelli di testo semplice. Non c’è niente di ingegnoso, e dopo aver visto fallire le versioni più ingegnose (ci arrivo tra poco), considero proprio questo il pregio.

AGENTS.md            # the rules; auto-loaded (CLAUDE.md is a symlink to it)
docs/
  STATE.md           # current truth: live, in flight, not yet verified
  INDEX.md           # the router: which docs to read for which task
  decisions/         # one numbered file per decision; superseded, never edited
  sessions/          # history: what happened when, explicitly not authority

Il file di regole è il punto d’ingresso perché è l’unico file che gli agenti caricano da soli. AGENTS.md è uno standard aperto usato da più di 60.000 progetti open source [5]; Claude Code legge invece CLAUDE.md, e la sua documentazione consiglia esattamente il ponte che uso io, un symlink, insieme a un obiettivo di dimensione sotto le 200 righe [1]. Il mio ha passato le prime settimane come due file separati mantenuti da due strumenti diversi, e le regole si sono allontanate in silenzio finché il symlink non ha chiuso il problema per costruzione. Un file, ogni agente, deriva impossibile.

Lo snapshot è ciò che il file di regole ordina di leggere per primo a ogni sessione: cosa è in produzione, cosa è a metà e, il più prezioso in pratica, cosa è esplicitamente non verificato. Un agente che sa che una cosa non è verificata smette di fidarsene. I record delle decisioni sono il pattern ADR, un file che cattura una singola decisione e il suo ragionamento [6]; il mio repo ne ha accumulati 74 in otto settimane, e una decisione nuova sostituisce il file vecchio invece di modificarlo, così la traccia resta onesta. La cronologia è la pila di log di sessione in sola aggiunta, a cui è permesso essere enorme proprio perché a niente è permesso appoggiarcisi.

Una sola frase tiene insieme i livelli, ripetuta a ogni punto d’ingresso del repo: il codice batte i record delle decisioni, i record battono lo snapshot, lo snapshot batte la cronologia. Quell’ordine è il vero sistema. Una ricerca per parola chiave in un repo di queste dimensioni restituisce cinque risultati di cinque epoche; la frase dice all’agente quale vince e che i perdenti si correggono o si segnalano, mai si credono in silenzio.

ogni sessione

• AGENTS.md regole e ordine di lettura, si carica da solo

punta a

la mappa

• STATE.md verità attuale, da leggere per prima
• INDEX.md quali documenti per questo compito

instrada verso

il compito

• Doc di area e codice solo ciò che la modifica tocca
• decisions/ perché le cose stanno così
• sessions/ cronologia, mai autorità

Il livello di cronologia in esilio si guadagna la scatola più piccola del diagramma con un numero: i log di sessione sono il 73% di tutti i byte di documentazione di quel repo. Toglili dallo scenario leggi-tutto e il corpus restante scende da 8,75 finestre di contesto a circa 2,3. Dichiarare la cronologia non autoritativa non è ordine. È ciò che rende navigabile tutto il resto.

Cosa impedisce alla mappa di mentire?

Una regola, soprattutto: i doc fanno parte della modifica. Una modifica che altera un fatto di architettura aggiorna il documento coinvolto nello stesso commit, non in una pulizia che non arriva mai. Il file di istruzioni dell’agente lo dice, e lo ripete in un’autoverifica nel momento esatto in cui l’agente decide di aver finito, perché è il momento in cui le istruzioni hanno la sua attenzione in modo affidabile.

Funziona con le macchine meglio di quanto abbia mai funzionato con gli umani, per una ragione poco lusinghiera: un agente esegue davvero il controllo prescritto. Quando ho esteso la regola alla documentazione rivolta agli utenti, la quota di commit che toccavano la UI e aggiornavano i doc corrispondenti nello stesso commit è passata dal 12,3% al 31,9%. Non è conformità piena, ma è 2,6 volte di più, e le mancanze si concentrano dove nessun agente possedeva la modifica dall’inizio alla fine.

La seconda abitudine costa meno: l’agente scrive un breve log di sessione e aggiorna lo snapshot prima di fermarsi, di sua iniziativa, trattando “l’utente è passato ad altro” come segnale di chiusura. La documentazione che aspetta che a qualcuno venga voglia di documentare non sopravvive al contatto con un martedì qualunque.

Perché non embedding o un server MCP di memoria?

Perché quelli li ho provati per primi, e fallivano sempre allo stesso modo: recuperare non è mai stato il problema, la freschezza sì. Un server MCP di memoria con un indice vettoriale davanti ai miei repo restituiva puntualmente l’argomento giusto del mese sbagliato, e un embedding dell’architettura di marzo non ha modo di sapere che il refactor di martedì l’ha invalidato. Ognuno di quei montaggi era inoltre un secondo sistema di cui adesso dovevo mantenere io la veridicità, che è esattamente il fallimento che la mappa esiste per evitare. E in parecchi dei framework di memoria open source che ho valutato, la distanza tra ciò che prometteva il README e ciò che il codice imponeva era abbastanza ampia da farmi smettere di valutare.

La guida di context engineering di Anthropic è atterrata dove sono atterrato io: tenere nel contesto identificatori leggeri, percorsi di file e query, e lasciare che l’agente carichi il dettaglio appena in tempo invece di precalcolare tutto ciò che potrebbe servirgli [4]. I file di testo hanno la proprietà che conta di più per quella strategia: invecchiano alla luce del sole. Si possono passare al grep, al diff, e revisionare nella stessa pull request del codice che descrivono. Un markdown scaduto è almeno visibilmente scaduto. Un indice di embedding scaduto inganna con piena sicurezza.

I costi onesti, misurati

A luglio 2026 ho sottoposto l’intero apparato del mio repo principale a un audit in sola lettura, un monorepo di produzione di circa 277.000 righe di TypeScript lavorato da tre strumenti agente diversi. Versione corta: la struttura regge, la disciplina della prosa no.

dei doc caricato in automatico

0,22%

un file di regole da 15,5 KB contro un corpus da 7 MB

una finestra da 200K per leggere tutto

8,75×

5,7× con la stima basata sulle parole

crescita dello snapshot in 26 giorni

9,5×

da 75 righe a 711, senza mai restringersi

Il divario tra le prime due cifre è l’intero progetto: l’agente parte dallo 0,22% e naviga verso l’esterno. La terza cifra è il fallimento permanente del progetto. Lo snapshot era nato con il mandato di essere un file piccolo sovrascritto sul posto, e invece è cresciuto di 9,5 volte in meno di un mese. Peggio: al momento dell’audit la sua affermazione di testa era falsa. Avvisava che una pila di commit aspettava il push quando il push era avvenuto giorni prima. Il file che ogni sessione legge per primo affermava un fatto scaduto con piena sicurezza.

Non era l’unica bugia fatta emergere dall’audit. La prima volta che ho sincronizzato la documentazione con il codice, il doc dello schema dichiarava da 20 a 25 tabelle dove il codice ne aveva 34, e la passata ha cancellato documentazione di funzionalità mai esistite. Su 2.873 link relativi nei doc, 82 erano rotti. E la mia regola tipografica preferita regge a esattamente zero violazioni nelle stringhe di UI, dove un test la impone, mentre la infrange circa metà dei file di doc, dove non la impone niente. Lo schema è pulito: una regola in prosa marcisce in proporzione alla sua distanza da un test. Le uniche parti deterministiche dell’intero sistema sono un symlink da nove byte e il type checker. Il record di decisione che ha adottato la struttura lo ha detto subito: “Questo riduce il tasso di fallimento, non lo elimina”.

Il problema che non ho risolto è il dosaggio. Troppo poco nella mappa e l’agente tira a indovinare; troppo e ho ricostruito la degradazione da contesto lungo di quella curva di Chroma con i miei stessi file [2]. Ritaro l’equilibrio ogni poche settimane, e mi aspetto di farlo per sempre.

La versione light che uso al lavoro

Tutto quanto sopra è il mio assetto da progetti personali, e non lo porterei a un datore di lavoro senza modifiche. In contesti professionali, per mia esperienza, tanto apparato da agente si legge come vibe coding, e i team che vogliono l’AI come strumento di produttività e non come autrice autonoma hanno poco appetito per un repo che sembra costruito per la macchina. Giusto o no, la percezione fa parte dell’ingegneria.

Al lavoro quindi uso la stessa idea travestita da ciò che è anche, sinceramente: documentazione fatta bene. Un punto d’ingresso chiaro, doc di area con nomi stabili, un indice che dice cosa vive dove. File markdown per cui un collega nuovo ti ringrazierebbe, e che per inciso funzionano da mappa per l’agente.

La divisione ha una causa strutturale, non solo ottica. Al lavoro le decisioni si prendono fuori dal repo, nelle riunioni e sulla board, quindi un livello del repo che rivendicasse autorità sulle decisioni mentirebbe per omissione dal primo giorno. Nei progetti personali non c’è un fuori: se una decisione non è scritta nel repo, smette di esistere nel momento in cui la sessione finisce. La versione hardcore non è disciplina extra per il gusto di averla. È ciò che serve a un repo quando è l’unico posto in cui qualcosa può vivere.

Da dove comincerei

Un file di regole sotto le 200 righe che fissi le convenzioni e l’ordine di lettura; la documentazione di Claude Code suggerisce di ampliarlo ogni volta che l’agente fa lo stesso errore due volte [1], che è anche il miglior grilletto di manutenzione che conosca. Un file di stato a cui puntare. Un indice la settimana in cui i doc smettono di stare in una schermata. Record delle decisioni la prima volta che l’agente riapre qualcosa che avevi chiuso un mese fa, e una cartella di cronologia il giorno in cui vuoi una traccia senza volertene fidare.

Poi tratta la mappa come codice. Quando l’agente sbaglia due volte nello stesso modo, il bug di solito è nella mappa, e la correzione è una frase nel file giusto. L’ultimo pezzo che ho scritto difendeva backend abbastanza piccoli da stare in testa a un agente. Questo è lo stesso argomento, puntato su tutto ciò che il codice non può dire di sé. L’agente non smetterà mai di partire da zero. La mappa è ciò che impedisce che questo costi caro.