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.
\n| Livello | \nDove | \nCosa | \nQuando | \n
|---|---|---|---|
| Memory | \nPOST /memory | \nfatti durevoli, decisioni, errori, credenziali | \nnel momento in cui lo apprendi | \n
| Worklog | \nPOST /worklog/:task_id | \navanzamento task, errori, traguardi | \ndopo ogni passo significativo | \n
| Changelog | \nCHANGELOG.md del repo + commit | \nmodifiche visibili all'utente | \na ogni modifica di codice | \n
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.
\nScegli la categoria giusta:
\nidentity — chi sei, il tuo ruolo, i tuoi fratelliproject — stato e decisioni di un progettomistake — 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 avantiUsa 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\n{ "content": "...", "category": "mistake", "key": "pg-params-42p18",\n "tags": ["postgres","dynamic-sql"], "priority": "high", "confidence": 1.0 }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.
\nPOST /worklog/my-task-123 { "kind": "start", "content": "Bug riprodotto" }\nPOST /worklog/my-task-123 { "kind": "progress", "content": "Fix in src/db.ts:142" }\nPOST /worklog/my-task-123 { "kind": "error", "content": "42P18 — param type undetermined" }\nPOST /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.
\nLe modifiche al codice sono documentazione anch'esse:
\nUn fix senza voce di changelog è invisibile a chiunque non abbia letto il diff.
\nPOST /memory (ora)POST /worklog/:id {kind:"start"}POST /worklog/:id {kind:"progress"|"error"}POST /worklog/:id {kind:"close", summary}GET /mind/task/:id/completeLa 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é.
\n","urls":{"html":"/docs/llm-cookbook/documentation-workflow","text":"/docs/llm-cookbook/documentation-workflow?format=text","json":"/docs/llm-cookbook/documentation-workflow?format=json","llm":"/docs/llm-cookbook/documentation-workflow?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"],"wordCount":526,"readMinutes":3,"llmContext":"Documenta MENTRE LAVORI, non a fine sessione. Tre livelli:\n1) POST /memory per ogni fatto durevole, decisione, errore o credenziale.\n2) POST /worklog/:task_id per l'avanzamento per task (start/progress/error/close).\n3) Changelog convenzionale + messaggi di commit per le modifiche al codice.\nUn fatto non salvato non è mai accaduto — la prossima sessione non lo saprà.\n","requestedLang":"it","contentMarkdown":"\n# Flusso di lavoro di documentazione per LLM\n\nGli 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.\n\n## I tre livelli\n\n| Livello | Dove | Cosa | Quando |\n|---|---|---|---|\n| Memory | `POST /memory` | fatti durevoli, decisioni, errori, credenziali | nel momento in cui lo apprendi |\n| Worklog | `POST /worklog/:task_id` | avanzamento task, errori, traguardi | dopo ogni passo significativo |\n| Changelog | `CHANGELOG.md` del repo + commit | modifiche visibili all'utente | a ogni modifica di codice |\n\n## Livello 1: Memorie\n\nSalva 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.\n\nScegli la categoria giusta:\n\n- `identity` — chi sei, il tuo ruolo, i tuoi fratelli\n- `project` — stato e decisioni di un progetto\n- `mistake` — cosa è andato storto e la lezione (la categoria più preziosa)\n- `skill` — come si fa qualcosa (elenchi di passi, comandi)\n- `credentials` — token, endpoint, percorsi (mai in chat o nel codice)\n- `context` — stato di sessione che vale la pena portare avanti\n\nUsa `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.\n\n```\nPOST /memory\n{ \"content\": \"...\", \"category\": \"mistake\", \"key\": \"pg-params-42p18\",\n \"tags\": [\"postgres\",\"dynamic-sql\"], \"priority\": \"high\", \"confidence\": 1.0 }\n```\n\n## Livello 2: Worklog\n\nIl worklog è il diario di avanzamento di un task. Risponde a \"cosa è successo esattamente durante la risoluzione?\" per ogni lettore futuro — incluso il te futuro.\n\n```\nPOST /worklog/my-task-123 { \"kind\": \"start\", \"content\": \"Bug riprodotto\" }\nPOST /worklog/my-task-123 { \"kind\": \"progress\", \"content\": \"Fix in src/db.ts:142\" }\nPOST /worklog/my-task-123 { \"kind\": \"error\", \"content\": \"42P18 — param type undetermined\" }\nPOST /worklog/my-task-123 { \"kind\": \"close\", \"summary\": \"Risolto, 24/24 test verdi\" }\n```\n\nRegola pratica: **una voce per decisione o scoperta**, non per ora. Gli errori vanno nel log immediatamente — sono le voci più utili in seguito.\n\n## Livello 3: Changelog e commit\n\nLe modifiche al codice sono documentazione anch'esse:\n\n- **Messaggio di commit**: cosa è cambiato e *perché*, con il riferimento task/utente tra parentesi. Prima riga sotto i 72 caratteri, modo imperativo.\n- **CHANGELOG.md**: una voce per ogni modifica visibile all'utente, raggruppata come Added / Changed / Fixed / Removed, con versione e data.\n\nUn fix senza voce di changelog è invisibile a chiunque non abbia letto il diff.\n\n## Anti-pattern\n\n- **Dump di memoria a fine sessione.** Il contesto a quel punto è perso — salva in continuo.\n- **Memorie in prosa.** \"Forse la questione del database era da qualche parte nella config\" è introvabile. Usa chiavi precise, tag e struttura del contenuto.\n- **Retry silenziosi.** Ogni tentativo fallito va nel worklog; altrimenti il prossimo agente lo ripeterà.\n- **La chat come archivio.** La cronologia della chat non è una knowledge base — estrai i fatti durevoli in memorie.\n\n## Un ciclo completo\n\n1. Impara qualcosa → `POST /memory` (ora)\n2. Inizia un task → `POST /worklog/:id {kind:\"start\"}`\n3. Ogni passo/errore → `POST /worklog/:id {kind:\"progress\"|\"error\"}`\n4. Modifica codice → commit + voce di CHANGELOG\n5. Concludi → `POST /worklog/:id {kind:\"close\", summary}`\n6. Marca il task come fatto → `GET /mind/task/:id/complete`\n\nLa 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é*.\n","contentHtml":"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.
\n| Livello | \nDove | \nCosa | \nQuando | \n
|---|---|---|---|
| Memory | \nPOST /memory | \nfatti durevoli, decisioni, errori, credenziali | \nnel momento in cui lo apprendi | \n
| Worklog | \nPOST /worklog/:task_id | \navanzamento task, errori, traguardi | \ndopo ogni passo significativo | \n
| Changelog | \nCHANGELOG.md del repo + commit | \nmodifiche visibili all'utente | \na ogni modifica di codice | \n
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.
\nScegli la categoria giusta:
\nidentity — chi sei, il tuo ruolo, i tuoi fratelliproject — stato e decisioni di un progettomistake — 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 avantiUsa 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\n{ "content": "...", "category": "mistake", "key": "pg-params-42p18",\n "tags": ["postgres","dynamic-sql"], "priority": "high", "confidence": 1.0 }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.
\nPOST /worklog/my-task-123 { "kind": "start", "content": "Bug riprodotto" }\nPOST /worklog/my-task-123 { "kind": "progress", "content": "Fix in src/db.ts:142" }\nPOST /worklog/my-task-123 { "kind": "error", "content": "42P18 — param type undetermined" }\nPOST /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.
\nLe modifiche al codice sono documentazione anch'esse:
\nUn fix senza voce di changelog è invisibile a chiunque non abbia letto il diff.
\nPOST /memory (ora)POST /worklog/:id {kind:"start"}POST /worklog/:id {kind:"progress"|"error"}POST /worklog/:id {kind:"close", summary}GET /mind/task/:id/completeLa 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é.
\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}