Handoff fra sessioni: un agente di coding che non perde il filo

Un agente di coding comincia ogni sessione senza ricordare niente della precedente. Per farlo lavorare per settimane sullo stesso prodotto gli diamo un file solo da leggere per primo, docs/HANDOFF.md, che dice dove siamo, cosa è in produzione, cosa è aperto e come si riprende. La regola che lo tiene vivo è una: chi lavora lo riscrive alla fine di ogni pezzo di lavoro, nella stessa sessione.

Le istruzioni di progetto non bastano. Nel CLAUDE.md di ogni repository stanno le regole (come si fanno le migration, dove vanno i segreti, come si usa git) e sono stabili, cambiano poche volte al mese. Lo stato dei lavori invece cambia ogni giorno, a volte ogni ora: una funzione appena pubblicata, una prova ancora da fare, una decisione presa a voce. Se finisse nelle istruzioni le renderebbe lunghe e presto sbagliate. Ha bisogno di un posto suo, e quel posto è il file di handoff. Nel repository dell'app iOS, che esiste da fine giugno, circa 140 commit su 660 toccano docs/HANDOFF.md; in quello della dashboard amministrativa sono 68 su 156. Non è burocrazia: è il prezzo, piccolo, di non dover rispiegare tutto ogni mattina.

Il file apre con un blocco che dice quando leggerlo: per primo, a ogni sessione nuova e dopo ogni volta che la conversazione si azzera. Poi poche sezioni, sempre le stesse: dove siamo, con la data, cioè cosa è in produzione, su quale branch, a che versione; l'ultimo lavoro, cioè cosa è stato chiesto, trovato, fatto e provato, una sezione che si riscrive e non si accumula; cosa è aperto, e di chi è; e in fondo un log, una riga per lavoro, per chi ha bisogno della storia. È corto di proposito. Il dettaglio sta nei documenti che linka.

Un handoff vecchio è peggio di niente

Nel nostro handoff c'è una frase che vale più delle altre: un handoff che non è dell'ultima cosa fatta è peggio di niente. Un file vecchio di due giorni non dice "non lo so", dice una cosa falsa con sicurezza, e un agente che lo legge parte da lì e ci costruisce sopra. Per questo l'aggiornamento non si rimanda a fine giornata e non si delega a una sessione successiva: lo fa chi ha lavorato, prima di chiudere. E per lo stesso motivo ogni affermazione di stato porta una data. Un "è in produzione" senza data non si può pesare; un "in produzione dall'8 ottobre" sì.

La distinzione più utile che abbiamo imparato a scrivere è fra fatto e verificato. Nell'handoff della dashboard, in fondo a ogni lavoro, c'è una riga che dice esattamente fin dove arriva la prova: types e build passati, le domande nuove provate contro il modello vero, la catena riletta dal database, e poi, in grassetto, non provato nel browser. A una persona sembra una cosa ovvia da tacere. A un agente che arriva il giorno dopo cambia tutto, perché sa che il prossimo passo non è aggiungere ma provare.

Le trappole si imparano una volta sola, se le si scrive dove si inciampa. In un periodo di lavoro intenso la produzione dell'app girava con commit più recenti di quelli sul repository remoto, e l'handoff diceva, con due punti esclamativi, di pubblicare le funzioni dal main locale e mai da quello remoto: farlo dal remoto avrebbe cancellato il lavoro già in produzione e riaperto un errore appena chiuso. Nella dashboard, invece, la piattaforma di hosting non segnala quando un deploy è finito, e uno screenshot arrivato due minuti e mezzo dopo un push mostrava ancora la versione vecchia. L'handoff lo dice: prima di cercare un bug, controllare che la pagina abbia i testi nuovi. Dieci parole che evitano un pomeriggio passato a correggere un codice che non era ancora online. E quando una scelta la fa una persona e non il codice, l'handoff la riporta con nome, data e a volte le parole esatte: "niente risposte senza modello di linguaggio: anche i convenevoli li scrive il modello". Una sessione successiva, che magari troverebbe ragionevole l'opposto, sa che la questione è chiusa e da chi.

Una mappa: quando leggere cosa

Accanto all'handoff c'è docs/README.md, con una tabella a due colonne: il file, e quando leggerlo. Non "di cosa parla", ma in quale momento serve. Un documento sulla previsione glicemica dice di leggerlo prima di toccare il motore di previsione; uno sul modello che classifica i messaggi apre con le tre cose da sapere prima di toccare qualsiasi cosa. Ogni documento comincia con lo stesso blocco, "quando leggere questo file", e segue lo stesso ordine: visione, stato reale verificato sul codice e sul database, cose da fare, log datato. Un cantiere, un file: se un documento comincia a parlare di due cose, si divide.

Lo stesso meccanismo funziona anche fra repository diversi. Quando il sito ha avuto bisogno che la dashboard gestisse i link verso l'App Store, la sessione che lavorava sul sito ha scritto un documento di passaggio per quella che avrebbe lavorato sulla dashboard: la tabella da usare, le colonne, chi legge e chi scrive, le cose da non fare. La sessione della dashboard ha costruito su quello, senza che nessuno dovesse rispiegare niente.

Gli strumenti di coding con memoria persistente salvano piccoli fatti fra una sessione e l'altra, e li usiamo. Ma servono a un'altra cosa: ricordano come si lavora con noi, non a che punto è il lavoro. Non avviare server di prova sulla porta che usano già altri processi; per i bug di scorrimento su iPhone, non fidarsi dell'emulazione e chiedere una prova sul telefono vero. Sono abitudini. Lo stato del lavoro deve stare nel repository, dove lo vedono tutte le sessioni e tutte le persone, e dove la storia di git dice chi l'ha cambiato e quando.

In sintesi:

• Un agente di coding non ricorda niente: lo stato del lavoro va scritto in un file che legge per primo.
• La sezione "ultimo lavoro" si riscrive, non si accumula; ogni affermazione di stato ha una data.
• Dichiarare cosa è stato provato e cosa no indica alla sessione successiva il prossimo passo.
• Le trappole e le decisioni umane vanno scritte dove si inciampa, con nomi e date.
• Le memorie dell'agente servono per le abitudini; lo stato dei lavori sta nel repository.