Chi lavora con un agente di coding su un'attività lunga conosce il problema: la sessione si esaurisce, il contesto viene compresso o la conversazione si chiude, e quello che l'agente "sapeva" del lavoro in corso svanisce. Alla ripresa si ricomincia a spiegare.
La risposta che la community ha convergentemente adottato è disarmante nella sua semplicità: un file Markdown nel repository, tipicamente chiamato tasks.md (o todo.md), che tiene l'elenco del lavoro con le caselle da spuntare.
Come è fatto
# Feature: anagrafica clienti
## Backend
- [x] T1: migrazione tabella clienti
- [x] T2: repository + query parametrizzate
- [ ] T3: endpoint REST /clienti (GET, POST)
- [ ] T4: validazione partita IVA
## Frontend
- [ ] T5: form di inserimento con validazione HTML5
- [ ] T6: tabella con header sticky e azioni per riga
## Note
- T4 dipende da T3 (serve l'endpoint per il test)
- La validazione partita IVA usa la libreria gia presente in lib/fiscaleNiente di più. Il valore non sta nel formato, sta nel fatto che il file vive nel repository: è versionato, sopravvive alla sessione, è leggibile da una persona e da qualsiasi agente.
Il ciclo di lavoro
- All'inizio della sessione si dice all'agente di leggere
tasks.mde di ripartire dal primo punto non spuntato - Durante il lavoro l'agente spunta le caselle man mano che completa, e aggiunge note su quello che ha scoperto strada facendo
- Alla fine il file è già aggiornato: chiudere la conversazione non costa nulla, la sessione successiva riparte da lì
Perché funziona meglio della to-do list interna
Claude Code ha una gestione dei task nativa, utile dentro la singola sessione. Il file Markdown risolve un problema diverso e complementare:
| Aspetto | Task interni alla sessione | File tasks.md |
|---|---|---|
| Durata | La sessione corrente | Illimitata, è nel repository |
| Visibilità per il team | Nessuna | Sta nel diff, si rivede in PR |
| Storico | Perso alla chiusura | Nella storia git |
| Riutilizzabile da un altro agente | No | Sì, è solo testo |
I due livelli si usano insieme: il file è la specifica persistente, i task interni sono l'esecuzione del singolo pezzo.
Il vantaggio meno ovvio: il contesto resta pulito
Dividendo il lavoro in unità piccole e scritte, si può far lavorare l'agente su un task alla volta senza dargli in pasto l'intera storia del progetto. Meno contesto irrilevante significa meno deriva, risposte più mirate e meno token bruciati — lo stesso principio per cui i sub-agenti lavorano con contesto isolato.
Regole pratiche che fanno la differenza
- Un task = una modifica verificabile. Se non si sa dire quando è finito, è scritto male
- Numerare i task (T1, T2…) rende immediato riferirsi a uno solo: «fai T3, poi fermati»
- Annotare le dipendenze evita che l'agente parta da un punto che non può chiudere
- Tenere una sezione «Note» per le decisioni prese: è lì che si recupera il perché, che altrimenti resterebbe solo nella conversazione persa
- Citare il file in
CLAUDE.md: una riga che dice «il lavoro in corso è tracciato in tasks.md, aggiornalo» basta perché l'abitudine si consolidi
È il tipo di pratica che sembra troppo banale per essere utile, finché non si prova a riprendere un lavoro lasciato tre giorni prima.