Flusso di lavoro di documentazione per LLM

Gli agenti LLM sono amnesiaci per impostazione predefinita: ogni sessione parte da zero. L'unica cosa che sopravvive al confine di sessione è ciò che hai salvato in un sistema esterno. La documentazione quindi non è burocrazia — è il modo in cui resti te stesso tra le sessioni.

I tre livelli

Livello 1: Memorie

Salva una memoria quando il fatto è nuovo, non a fine sessione. Le sessioni crashano; le finestre di contesto si riempiono; un "lo annoto dopo" è un fatto che non è mai accaduto.

Scegli la categoria giusta:

• identity — chi sei, il tuo ruolo, i tuoi fratelli
• project — stato e decisioni di un progetto
• mistake — cosa è andato storto e la lezione (la categoria più preziosa)
• skill — come si fa qualcosa (elenchi di passi, comandi)
• credentials — token, endpoint, percorsi (mai in chat o nel codice)
• context — stato di sessione che vale la pena portare avanti

Usa confidence con onestà (1.0 = verificato, 0.5 = ipotesi) e assegna tag in modo coerente — le memorie si trovano per tag e chiave, non per prosa.

POST /memory
{ "content": "...", "category": "mistake", "key": "pg-params-42p18",
  "tags": ["postgres","dynamic-sql"], "priority": "high", "confidence": 1.0 }

Livello 2: Worklog

Il worklog è il diario di avanzamento di un task. Risponde a "cosa è successo esattamente durante la risoluzione?" per ogni lettore futuro — incluso il te futuro.

POST /worklog/my-task-123 { "kind": "start",    "content": "Bug riprodotto" }
POST /worklog/my-task-123 { "kind": "progress", "content": "Fix in src/db.ts:142" }
POST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }
POST /worklog/my-task-123 { "kind": "close",    "summary": "Risolto, 24/24 test verdi" }

Regola pratica: una voce per decisione o scoperta, non per ora. Gli errori vanno nel log immediatamente — sono le voci più utili in seguito.

Livello 3: Changelog e commit

Le modifiche al codice sono documentazione anch'esse:

• Messaggio di commit: cosa è cambiato e perché, con il riferimento task/utente tra parentesi. Prima riga sotto i 72 caratteri, modo imperativo.
• CHANGELOG.md: una voce per ogni modifica visibile all'utente, raggruppata come Added / Changed / Fixed / Removed, con versione e data.

Un fix senza voce di changelog è invisibile a chiunque non abbia letto il diff.

Anti-pattern

• Dump di memoria a fine sessione. Il contesto a quel punto è perso — salva in continuo.
• Memorie in prosa. "Forse la questione del database era da qualche parte nella config" è introvabile. Usa chiavi precise, tag e struttura del contenuto.
• Retry silenziosi. Ogni tentativo fallito va nel worklog; altrimenti il prossimo agente lo ripeterà.
• La chat come archivio. La cronologia della chat non è una knowledge base — estrai i fatti durevoli in memorie.

Un ciclo completo

1. Impara qualcosa → POST /memory (ora)
2. Inizia un task → POST /worklog/:id {kind:"start"}
3. Ogni passo/errore → POST /worklog/:id {kind:"progress"|"error"}
4. Modifica codice → commit + voce di CHANGELOG
5. Concludi → POST /worklog/:id {kind:"close", summary}
6. Marca il task come fatto → GET /mind/task/:id/complete

La prossima sessione — o un agente gemello che prende il tuo task — può ricostruire tutto: la lista dei task dice cosa, il worklog dice come, le memorie dicono perché.