Quando l’AI dimentica il tuo progetto (e come evitarlo)

Succede a tutti. Lavori per giorni con un agente di coding AI: il primo giorno scrive API, test e documentazione. Il secondo, però, apri una nuova chat e l’agente non sa più niente. Devi rispiegare struttura, scelte e vincoli. Dopo qualche sessione finisci per rileggere migliaia di token solo per ricostruire il filo.

Il problema non è la finestra di contesto. È che teniamo lo stato del progetto nel posto sbagliato.

La memoria della chat è fragile

Le conversazioni vanno bene per parlare, ma sono pessime come database. Ogni decisione si perde nel flusso, non esiste una fonte unica di verità e ogni nuovo agente parte da zero. Con il tempo le incoerenze si accumulano: un agente sceglie una strategia di test, un altro la cambia, un terzo segna la documentazione come finita quando manca ancora metà del lavoro.

Il vero limite non è far scrivere codice all’AI. Il limite è farle capire cosa stai costruendo e perché.

La soluzione più noiosa (ma efficace)

Metti lo stato del progetto dove metti il codice: in file versionati dentro il repository. Non serve un wiki né un tool di project management. Basta Markdown strutturato con pochi metadati.

Ogni record ha un titolo, uno stato (attivo, completato, archiviato), un ruolo (spec, log, decisione, guida) e relazioni con altri file. Niente sintassi speciale, niente database. Solo testo leggibile da umani e macchine.

Un piccolo tool a riga di comando può creare, archiviare, spostare, elencare e validare questi record, mantenendo sempre aggiornato un indice automatico.

Come cambia il flusso di lavoro

Invece di chiedere all’agente di “rileggere la chat”, gli dai comandi precisi:

docs list --role=spec --lifecycle=active
docs check

L’agente interroga lo stato del progetto invece di scavare nella storia della conversazione. Vede cosa è deciso, cosa è in corso, cosa è bloccato. Può anche modificare lo stato con verbi semplici come docs create o docs archive, senza toccare direttamente i file.

Il “fresh agent pattern”

Ogni volta che apri una nuova sessione, l’agente esegue subito docs list, capisce quali milestone sono chiuse e quale è aperta, legge il log dell’ultima implementazione e controlla la specifica corrente. Niente più archeologia della chat: lo stato è nel repository, dove deve stare.

Quando ti serve davvero

Serve se usi tool di pair programming AI su progetti che durano più giorni, se gestisci agenti che devono riprendere il lavoro senza perdere contesto, o se lavori in team e vuoi una visione condivisa di cosa è deciso e cosa è ancora aperto.

Non sostituisce Git né i test. È solo il collante che tiene coerente lo sviluppo assistito dall’AI nel tempo.

La verità (poco glamour)

La forza di questo approccio sta proprio nella sua banalità. Usa Markdown, Git e CLI: strumenti che già conosci. I casi limite si risolvono con validazione e comandi espliciti, non con logica nascosta. Alla fine la differenza è semplice: o l’agente “più o meno funziona”, o capisce davvero il progetto e lo porta a termine.