I miei agenti di coding dimenticano il repo. Gli do una mappa

I miei agenti di coding non ricordano il repository tra una sessione e l’altra, quindi gli do un percorso di lettura fisso. Quattro livelli di file di testo indicano cosa è aggiornato, quali decisioni sono definitive e dove si trova il codice pertinente. L’agente usa meno contesto per riscoprire il codice, ma mantenere precisa la mappa resta la parte difficile.

Che cos’è un sistema di gestione del contesto? Un percorso di lettura fisso

Per una modifica alla fatturazione, il mio sistema di gestione del contesto manda l’agente a un indice che indica due documenti e una cartella. Questo percorso fisso sostituisce una ricerca estesa a tutto il repository, così l’agente comincia dai file che hanno più probabilità di servire.

La documentazione di Claude Code spiega perché serve un punto di partenza ripetibile: “Ogni sessione di Claude Code comincia con una finestra di contesto nuova” [1]. L’agente parte senza conoscere il repository e non può portare nella sessione successiva ciò che ha imparato. La continuità deve venire da informazioni che può ritrovare.

La mappa non cerca di contenere tutto ciò che potrebbe servire all’agente. Un file di istruzioni caricato automaticamente rimanda allo stato attuale, alle decisioni passate e alle posizioni pertinenti nel codice, mentre l’agente carica i dettagli solo quando il compito li richiede. La prima selezione conta perché diventa la base delle decisioni successive.

Quanto costa una sessione vuota? Token e precisione

Una sessione vuota costa sia in qualità sia in token, perché l’agente deve capire il sistema prima di poterlo modificare. Se dipende da corrispondenze tra parole chiave, può facilmente perdere dettagli importanti e produrre una modifica che sembra corretta, ma non lo è. Inoltre, la ricerca consuma contesto prima ancora che cominci il lavoro richiesto.

Caricare più file non risolve il problema da solo, perché un modello non mantiene lo stesso livello di attenzione lungo tutta una finestra di contesto estesa. Chroma Research ha testato 18 modelli e ha rilevato che le prestazioni diminuivano con l’aumentare dell’input, anche in attività che gli stessi modelli svolgevano bene con un prompt breve [2].

I contesti lunghi possono fallire in diversi modi, non solo esaurendo lo spazio. Drew Breunig spiega che gli errori iniziali possono influenzare il ragionamento successivo, le azioni passate possono distrarre il modello e parti diverse dell’input possono entrare in conflitto. Cita anche uno studio di Databricks in cui Llama 3.1 405B iniziava a perdere precisione intorno ai 32.000 token; oltre i 100.000 token, gli agenti diventavano meno efficaci anche con modelli dotati di finestre da un milione di token [3].

Il team di ingegneria di Anthropic descrive lo stesso limite come un budget di attenzione [4]. In pratica, ogni token speso per capire il repository lascia meno attenzione per la modifica richiesta.

I numeri del mio repository principale rendono impossibile evitare questa scelta. I suoi 418 file markdown contengono circa 7 MB di testo e leggerli tutti richiederebbe tra 5,7 e 8,75 volte una finestra di contesto da 200.000 token, a seconda del metodo di stima. L’agente deve leggerne solo una parte, quindi uso un ordine documentato invece di lasciare che la selezione dipenda dai primi risultati per parola chiave.

Quattro livelli di file danno priorità ai dati attuali

Il sistema fa passare ogni sessione attraverso regole, stato attuale, decisioni e cronologia facoltativa. Per tutti e quattro i livelli uso normali file del repository, facili da ispezionare, revisionare e aggiornare. Per me conta più questo di un sistema di ricerca sofisticato.

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

ogni sessione

• AGENTS.md regole e ordine di lettura, caricato automaticamente

rimanda a

la mappa

• STATE.md stato attuale, da leggere per primo
• INDEX.md quali documenti leggere per il compito

guida verso

il compito

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

Il file di regole viene per primo perché gli agenti lo caricano automaticamente. L’Agentic AI Foundation descrive AGENTS.md come uno standard aperto usato da oltre 60.000 progetti open source [5], mentre Claude Code legge CLAUDE.md. La documentazione di Claude Code consiglia il collegamento che uso: rendere CLAUDE.md un link simbolico ad AGENTS.md e tenere il file condiviso sotto le 200 righe [1].

All’inizio mantenevo un file separato per ogni strumento, ma col tempo le regole hanno cominciato a divergere. Il link simbolico ha eliminato questa fonte di differenze, perché ora entrambi gli strumenti ricevono lo stesso file e io devo aggiornare una sola copia.

Dal file di regole, ogni sessione passa al riepilogo dello stato. Questo elenca ciò che è in produzione, ciò che è ancora in corso e, soprattutto, ciò che non è stato verificato. L’ultima categoria impedisce all’agente di trattare come fatti un lavoro incompleto o un’ipotesi non controllata.

Dopo il riepilogo vengono le decisioni e la cronologia. Il progetto dedicato ai record di decisione architetturale (ADR) definisce ogni record come un documento su una singola decisione importante [6]; nel mio sistema, spiega sia la decisione sia il motivo. In otto settimane il mio repository ha accumulato 74 record e, quando una decisione cambia, un nuovo record sostituisce quello precedente invece di riscriverlo. I log di sessione hanno uno scopo diverso: formano una cronologia a cui si possono aggiungere nuove voci e che l’agente può consultare, ma mai come fonte dello stato attuale.

Un solo ordine di autorità risolve le risposte contraddittorie

Questi livelli funzionano solo se l’agente sa come risolvere i conflitti. Per questo, ogni punto di ingresso del repository dichiara lo stesso ordine di autorità: il codice prevale sui record delle decisioni, i record prevalgono sul riepilogo e il riepilogo prevale sulla cronologia. Quando una ricerca trova cinque risposte scritte in momenti diversi, l’agente può seguire la fonte con la priorità più alta e aggiornare o segnalare le altre.

Tenere la cronologia fuori dal normale percorso di lettura ha un effetto pratico notevole. I log di sessione rappresentano il 73% di tutti i byte della documentazione nel repository, quindi escluderli riduce la stima per leggere tutto da 8,75 finestre di contesto a circa 2,3. La documentazione attuale resta corposa, ma diventa molto più facile da percorrere.

Come tengo aggiornati i file di contesto? Documentazione e codice insieme

Tratto la documentazione come parte della modifica al codice. Quando il codice cambia un dato architetturale, lo stesso commit deve aggiornare il documento pertinente invece di rimandare il lavoro. Il file di istruzioni dichiara subito questa regola e la ripete nel controllo finale dell’agente, quando è più difficile dimenticare l’aggiornamento.

Nel mio repository, gli agenti hanno seguito questo controllo con maggiore regolarità rispetto alle persone. Dopo aver esteso la regola alla documentazione per gli utenti, la percentuale di commit dell’interfaccia che aggiornava anche i documenti corrispondenti è salita dal 12,3% al 31,9%. Un tasso del 31,9% è ben lontano dalla piena conformità, ma equivale a 2,6 volte il risultato precedente. La maggior parte delle omissioni proveniva da modifiche che nessun singolo agente aveva seguito dall’inizio alla fine.

Uso una seconda regola per le informazioni che cambiano tra le sessioni: prima di fermarsi, l’agente scrive un breve log di sessione e aggiorna il riepilogo. La stessa procedura scatta quando passa a un altro compito. Senza un momento preciso, gli aggiornamenti che sembrano facili da fare più tardi diventano altrettanto facili da dimenticare.

Perché ho smesso di usare embedding e server MCP di memoria

Ho smesso di usare entrambe le soluzioni perché il problema non era trovare le informazioni. I sistemi restituivano contenuti pertinenti, ma non riuscivano a stabilire in modo affidabile se fossero aggiornati. Il mio server MCP di memoria e l’indice vettoriale trovavano spesso l’argomento giusto del mese sbagliato, perché gli embedding creati prima di un refactor non sanno che l’architettura è cambiata.

Ogni soluzione creava anche un’altra fonte di informazioni da mantenere, riportando il problema che volevo risolvere. Alcuni framework di memoria open source ponevano un secondo problema: il loro codice spesso non imponeva il comportamento descritto nel README. Quando mi sono ritrovato a verificare sia l’attualità delle informazioni sia l’implementazione, ho smesso di valutarli. Gli agenti ospitati pongono la stessa domanda su che cosa resta tra una sessione e l’altra, un tema che tratto in che cosa conserva l’Agents API di OpenAI e che cosa gestisce l’harness di Codex.

Anthropic consiglia di mantenere nel contesto riferimenti leggeri, come percorsi dei file e query, e di caricare i dettagli solo quando servono all’agente [4]. I normali file si adattano bene a questo metodo perché si possono cercare, confrontare e revisionare nella stessa pull request del codice che descrivono. Un revisore può accorgersi che un file markdown è vecchio; un indice di embedding non aggiornato è molto più difficile da controllare.

Quanto è costato il sistema? Meno lettura, più manutenzione

Il sistema ha mantenuto il carico iniziale automatico allo 0,22% della documentazione del repository, ma non ha mantenuto aggiornata quella documentazione. Un controllo condotto a luglio 2026 ha scoperto che il riepilogo era cresciuto di 9,5 volte in 26 giorni e conteneva un avviso non più valido.

Il repository è un monorepo di produzione con circa 277.000 righe di TypeScript, su cui lavorano tre diversi strumenti basati su agenti. La struttura svolgeva il suo compito offrendo a ogni strumento un punto di ingresso breve e un ordine di lettura coerente. Le informazioni contenute in quella struttura erano molto meno affidabili. Come due degli attuali agenti di coding affrontano le funzionalità grandi è un confronto a parte: Claude contro Codex su grandi feature multi-agente.

della documentazione caricata automaticamente

0,22%

un file di regole da 15,5 KB rispetto a un insieme da 7 MB

una finestra da 200.000 token per leggere tutto

8,75×

5,7× con la stima basata sulle parole

crescita del riepilogo in 26 giorni

9,5×

da 75 a 711 righe, senza mai ridursi

Le prime due cifre mostrano il vantaggio dell’ordine di lettura: l’agente comincia con lo 0,22% della documentazione e carica altro solo quando il compito lo richiede. La terza espone il punto debole che il sistema non ha risolto. STATE.md avrebbe dovuto restare breve ed essere riscritto nello stesso file, ma in meno di un mese è cresciuto di 9,5 volte e, durante il controllo, il suo avviso principale era sbagliato. Indicava diversi commit ancora da inviare, anche se il push era avvenuto giorni prima.

L’avviso non aggiornato non era un caso isolato. La documentazione dello schema indicava tra 20 e 25 tabelle, mentre il codice ne conteneva 34. Il controllo ha anche eliminato la documentazione di funzionalità che non erano mai esistite. Infine, ha verificato 2.873 link relativi nei documenti e ne ha trovati 82 non funzionanti.

La differenza più costante emersa dal controllo era quella tra istruzioni scritte e verifiche automatiche. Un test fa rispettare la mia regola tipografica nelle stringhe dell’interfaccia, dove il controllo non ha trovato violazioni. Circa la metà dei normali file di documentazione infrangeva la stessa regola perché nessun test la verificava. In pratica, il link simbolico e il type checker erano gli unici elementi applicati in modo deterministico. Il record della decisione che ha introdotto il sistema aveva dichiarato chiaramente il limite: “Questo riduce il tasso di errore, non lo elimina”.

Non ho ancora trovato la quantità giusta di informazioni da caricare. Se i file iniziali contengono troppo poco, l’agente deve indovinare; se contengono troppo, ricreo il problema dei contesti lunghi misurato da Chroma Research [2]. L’equilibrio cambia insieme al repository, quindi lo regolo ogni poche settimane invece di considerare definitiva la struttura.

Al lavoro tengo il percorso di lettura e semplifico il resto

Al lavoro conservo l’idea del percorso di lettura, ma la presento come normale documentazione di progetto. La struttura completa resta nei miei progetti personali perché, nella mia esperienza, molti team interpretano un sistema così specifico per gli agenti come vibe coding e non come documentazione per sviluppatori.

In pratica, la versione per il lavoro assomiglia alla normale documentazione di un progetto: un punto di ingresso chiaro, documenti stabili per ogni area e un indice che spiega dove trovare le informazioni. I file markdown aiutano i nuovi colleghi, e anche gli agenti possono seguirli.

Le due versioni non differiscono solo nell’aspetto. Al lavoro, i team prendono decisioni durante le riunioni e sulle board di pianificazione, quindi il repository non può contenere l’intera cronologia quando gran parte di essa vive altrove. Nei miei progetti personali non esiste un registro esterno equivalente; se non scrivo una decisione nel repository, la sessione successiva non può trovarla.

Come iniziare: un file di regole sotto le 200 righe

Io inizierei con un file di regole sotto le 200 righe che indichi le convenzioni del repository e l’ordine in cui l’agente deve leggere gli altri file. La documentazione di Claude Code suggerisce di aggiungere una regola quando l’agente ripete un errore [1], e io uso lo stesso segnale per la manutenzione. Un errore ripetuto indica che il percorso di lettura non ha spiegato qualcosa con sufficiente chiarezza.

Il resto può arrivare quando serve. Aggiungi un file di stato e collegalo dalle regole, poi crea un indice quando la documentazione non sta più in una sola schermata. Scrivi il primo record di decisione quando un agente mette in dubbio una scelta che hai già definito e aggiungi una cartella per la cronologia quando ti serve un registro del lavoro passato che non venga scambiato per lo stato attuale. Anche un percorso di lettura chiaro ha cambiato quanto bene un modello lavora per me, come racconto nel mio workflow con Opus 5 fatto di piani chiari e attività più brevi.

Da lì, mantieni i file con la stessa cura del codice. Il mio articolo precedente consigliava backend abbastanza piccoli da poter essere compresi da un agente; questo sistema applica lo stesso principio alle informazioni che il codice non può spiegare da solo. L’agente continuerà a iniziare ogni sessione senza memoria, ma un percorso mantenuto con cura gli permette di trovare il contesto giusto senza leggere tutto il repository.