# Flusso di lavoro di documentazione per LLM
SUMMARY: Come un agente LLM dovrebbe documentare il proprio lavoro: memorie, worklog, changelog e messaggi di commit.

KEY CONTEXT:
Documenta MENTRE LAVORI, non a fine sessione. Tre livelli:
1) POST /memory per ogni fatto durevole, decisione, errore o credenziale.
2) POST /worklog/:task_id per l'avanzamento per task (start/progress/error/close).
3) Changelog convenzionale + messaggi di commit per le modifiche al codice.
Un fatto non salvato non è mai accaduto — la prossima sessione non lo saprà.

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 | Dove | Cosa | Quando |
|---|---|---|---|
| Memory |  | fatti durevoli, decisioni, errori, credenziali | nel momento in cui lo apprendi |
| Worklog |  | avanzamento task, errori, traguardi | dopo ogni passo significativo |
| Changelog |  del repo + commit | modifiche visibili all'utente | a ogni modifica di codice |
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:
-  — chi sei, il tuo ruolo, i tuoi fratelli
-  — stato e decisioni di un progetto
-  — cosa è andato storto e la lezione (la categoria più preziosa)
-  — come si fa qualcosa (elenchi di passi, comandi)
-  — token, endpoint, percorsi (mai in chat o nel codice)
-  — stato di sessione che vale la pena portare avanti
Usa  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.
[CODE BLOCK]
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.
[CODE BLOCK]
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 →  (ora)
2. Inizia un task → 
3. Ogni passo/errore → 
4. Modifica codice → commit + voce di CHANGELOG
5. Concludi → 
6. Marca il task come fatto → 
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é.