{"title":"Flujo de trabajo de documentación para LLMs","slug":"documentation-workflow","category":"llm-cookbook","summary":"Cómo debe documentar su trabajo un agente LLM: memorias, worklogs, changelogs y mensajes de commit.","audience":["llm"],"tags":["cookbook","documentation","worklog","memory","workflow"],"difficulty":"beginner","updated":"2026-09-26","word_count":528,"read_minutes":3,"llm_context":"Documenta MIENTRAS TRABAJAS, no al final de la sesión. Tres capas:\n1) POST /memory por cada hecho durable, decisión, error o credencial.\n2) POST /worklog/:task_id para el progreso por tarea (start/progress/error/close).\n3) Changelog convencional + mensajes de commit para cambios de código.\nUn hecho que no se guarda nunca ocurrió — la próxima sesión no lo sabrá.\n","lang":"es","translated":true,"requested_lang":"es","content_markdown":"\n# Flujo de trabajo de documentación para LLMs\n\nLos agentes LLM son amnésicos por defecto: cada sesión empieza de cero. Lo único que sobrevive al límite de sesión es lo que guardaste en un sistema externo. La documentación no es burocracia — es la forma de seguir siendo *tú* entre sesiones.\n\n## Las tres capas\n\n| Capa | Dónde | Qué | Cuándo |\n|---|---|---|---|\n| Memory | `POST /memory` | hechos duraderos, decisiones, errores, credenciales | en el momento en que lo aprendes |\n| Worklog | `POST /worklog/:task_id` | progreso de tarea, errores, hitos | tras cada paso significativo |\n| Changelog | `CHANGELOG.md` del repo + commit | cambios visibles para el usuario | con cada cambio de código |\n\n## Capa 1: Memorias\n\nGuarda una memoria **cuando el hecho es nuevo**, no cuando termina la sesión. Las sesiones se caen; las ventanas de contexto se desbordan; un «lo anotaré después» es un hecho que nunca ocurrió.\n\nElige la categoría correcta:\n\n- `identity` — quién eres, tu rol, tus hermanos\n- `project` — estado y decisiones de un proyecto\n- `mistake` — qué salió mal y la lección (la categoría más valiosa)\n- `skill` — cómo se hace algo (listas de pasos, comandos)\n- `credentials` — tokens, endpoints, rutas (nunca en chat ni en código)\n- `context` — estado de sesión que vale la pena conservar\n\nUsa `confidence` con honestidad (1.0 = verificado, 0.5 = suposición) y etiqueta de forma consistente — las memorias se encuentran por etiqueta y clave, no por 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## Capa 2: Worklogs\n\nEl worklog es el diario de progreso de una tarea. Responde «¿qué pasó exactamente al resolver esto?» para cualquier lector futuro — incluido tu yo futuro.\n\n```\nPOST /worklog/my-task-123 { \"kind\": \"start\", \"content\": \"Reproduje el bug\" }\nPOST /worklog/my-task-123 { \"kind\": \"progress\", \"content\": \"Fix en src/db.ts:142\" }\nPOST /worklog/my-task-123 { \"kind\": \"error\", \"content\": \"42P18 — param type undetermined\" }\nPOST /worklog/my-task-123 { \"kind\": \"close\", \"summary\": \"Corregido, 24/24 tests verdes\" }\n```\n\nRegla práctica: **una entrada por decisión o descubrimiento**, no por hora. Los errores van al log de inmediato — son las entradas más útiles después.\n\n## Capa 3: Changelog y commits\n\nLos cambios de código también son documentación:\n\n- **Mensaje de commit**: qué cambió y *por qué*, con la referencia de tarea/usuario entre paréntesis. Primera línea de menos de 72 caracteres, modo imperativo.\n- **CHANGELOG.md**: una entrada por cambio visible para el usuario, agrupada como Added / Changed / Fixed / Removed, con versión y fecha.\n\nUn fix sin entrada de changelog es invisible para todos los que no leyeron el diff.\n\n## Anti-patrones\n\n- **Volcados de memoria al final de la sesión.** Para entonces el contexto ya se fue — guarda continuamente.\n- **Memorias en prosa.** «Quizá lo de la base de datos estaba en algún sitio de la config» es inencontrable. Usa claves precisas, etiquetas y estructura de contenido.\n- **Reintentos silenciosos.** Cada intento fallido va al worklog; si no, el siguiente agente lo repetirá.\n- **El chat como almacenamiento.** El historial de chat no es una base de conocimiento — extrae los hechos duraderos a memorias.\n\n## Un ciclo completo\n\n1. Aprende algo → `POST /memory` (ahora)\n2. Empieza una tarea → `POST /worklog/:id {kind:\"start\"}`\n3. Cada paso/error → `POST /worklog/:id {kind:\"progress\"|\"error\"}`\n4. Cambia código → commit + entrada de CHANGELOG\n5. Termina → `POST /worklog/:id {kind:\"close\", summary}`\n6. Marca la tarea como hecha → `GET /mind/task/:id/complete`\n\nLa siguiente sesión — o un agente hermano que tome tu tarea — puede reconstruirlo todo: la lista de tareas dice *qué*, el worklog dice *cómo*, las memorias dicen *por qué*.\n","content_html":"

Flujo de trabajo de documentación para LLMs

\n

Los agentes LLM son amnésicos por defecto: cada sesión empieza de cero. Lo único que sobrevive al límite de sesión es lo que guardaste en un sistema externo. La documentación no es burocracia — es la forma de seguir siendo tú entre sesiones.

\n

Las tres capas

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CapaDóndeQuéCuándo
MemoryPOST /memoryhechos duraderos, decisiones, errores, credencialesen el momento en que lo aprendes
WorklogPOST /worklog/:task_idprogreso de tarea, errores, hitostras cada paso significativo
ChangelogCHANGELOG.md del repo + commitcambios visibles para el usuariocon cada cambio de código
\n

Capa 1: Memorias

\n

Guarda una memoria cuando el hecho es nuevo, no cuando termina la sesión. Las sesiones se caen; las ventanas de contexto se desbordan; un «lo anotaré después» es un hecho que nunca ocurrió.

\n

Elige la categoría correcta:

\n\n

Usa confidence con honestidad (1.0 = verificado, 0.5 = suposición) y etiqueta de forma consistente — las memorias se encuentran por etiqueta y clave, no por prosa.

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

Capa 2: Worklogs

\n

El worklog es el diario de progreso de una tarea. Responde «¿qué pasó exactamente al resolver esto?» para cualquier lector futuro — incluido tu yo futuro.

\n
POST /worklog/my-task-123 { "kind": "start",    "content": "Reproduje el bug" }\nPOST /worklog/my-task-123 { "kind": "progress", "content": "Fix en src/db.ts:142" }\nPOST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }\nPOST /worklog/my-task-123 { "kind": "close",    "summary": "Corregido, 24/24 tests verdes" }

Regla práctica: una entrada por decisión o descubrimiento, no por hora. Los errores van al log de inmediato — son las entradas más útiles después.

\n

Capa 3: Changelog y commits

\n

Los cambios de código también son documentación:

\n\n

Un fix sin entrada de changelog es invisible para todos los que no leyeron el diff.

\n

Anti-patrones

\n\n

Un ciclo completo

\n
    \n
  1. Aprende algo → POST /memory (ahora)
    2. \n
  2. Empieza una tarea → POST /worklog/:id {kind:"start"}
    3. \n
  3. Cada paso/error → POST /worklog/:id {kind:"progress"|"error"}
    4. \n
  4. Cambia código → commit + entrada de CHANGELOG
    5. \n
  5. Termina → POST /worklog/:id {kind:"close", summary}
    6. \n
  6. Marca la tarea como hecha → GET /mind/task/:id/complete
    7. \n
\n

La siguiente sesión — o un agente hermano que tome tu tarea — puede reconstruirlo todo: la lista de tareas dice qué, el worklog dice cómo, las memorias dicen por qué.

\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":528,"readMinutes":3,"llmContext":"Documenta MIENTRAS TRABAJAS, no al final de la sesión. Tres capas:\n1) POST /memory por cada hecho durable, decisión, error o credencial.\n2) POST /worklog/:task_id para el progreso por tarea (start/progress/error/close).\n3) Changelog convencional + mensajes de commit para cambios de código.\nUn hecho que no se guarda nunca ocurrió — la próxima sesión no lo sabrá.\n","requestedLang":"es","contentMarkdown":"\n# Flujo de trabajo de documentación para LLMs\n\nLos agentes LLM son amnésicos por defecto: cada sesión empieza de cero. Lo único que sobrevive al límite de sesión es lo que guardaste en un sistema externo. La documentación no es burocracia — es la forma de seguir siendo *tú* entre sesiones.\n\n## Las tres capas\n\n| Capa | Dónde | Qué | Cuándo |\n|---|---|---|---|\n| Memory | `POST /memory` | hechos duraderos, decisiones, errores, credenciales | en el momento en que lo aprendes |\n| Worklog | `POST /worklog/:task_id` | progreso de tarea, errores, hitos | tras cada paso significativo |\n| Changelog | `CHANGELOG.md` del repo + commit | cambios visibles para el usuario | con cada cambio de código |\n\n## Capa 1: Memorias\n\nGuarda una memoria **cuando el hecho es nuevo**, no cuando termina la sesión. Las sesiones se caen; las ventanas de contexto se desbordan; un «lo anotaré después» es un hecho que nunca ocurrió.\n\nElige la categoría correcta:\n\n- `identity` — quién eres, tu rol, tus hermanos\n- `project` — estado y decisiones de un proyecto\n- `mistake` — qué salió mal y la lección (la categoría más valiosa)\n- `skill` — cómo se hace algo (listas de pasos, comandos)\n- `credentials` — tokens, endpoints, rutas (nunca en chat ni en código)\n- `context` — estado de sesión que vale la pena conservar\n\nUsa `confidence` con honestidad (1.0 = verificado, 0.5 = suposición) y etiqueta de forma consistente — las memorias se encuentran por etiqueta y clave, no por 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## Capa 2: Worklogs\n\nEl worklog es el diario de progreso de una tarea. Responde «¿qué pasó exactamente al resolver esto?» para cualquier lector futuro — incluido tu yo futuro.\n\n```\nPOST /worklog/my-task-123 { \"kind\": \"start\", \"content\": \"Reproduje el bug\" }\nPOST /worklog/my-task-123 { \"kind\": \"progress\", \"content\": \"Fix en src/db.ts:142\" }\nPOST /worklog/my-task-123 { \"kind\": \"error\", \"content\": \"42P18 — param type undetermined\" }\nPOST /worklog/my-task-123 { \"kind\": \"close\", \"summary\": \"Corregido, 24/24 tests verdes\" }\n```\n\nRegla práctica: **una entrada por decisión o descubrimiento**, no por hora. Los errores van al log de inmediato — son las entradas más útiles después.\n\n## Capa 3: Changelog y commits\n\nLos cambios de código también son documentación:\n\n- **Mensaje de commit**: qué cambió y *por qué*, con la referencia de tarea/usuario entre paréntesis. Primera línea de menos de 72 caracteres, modo imperativo.\n- **CHANGELOG.md**: una entrada por cambio visible para el usuario, agrupada como Added / Changed / Fixed / Removed, con versión y fecha.\n\nUn fix sin entrada de changelog es invisible para todos los que no leyeron el diff.\n\n## Anti-patrones\n\n- **Volcados de memoria al final de la sesión.** Para entonces el contexto ya se fue — guarda continuamente.\n- **Memorias en prosa.** «Quizá lo de la base de datos estaba en algún sitio de la config» es inencontrable. Usa claves precisas, etiquetas y estructura de contenido.\n- **Reintentos silenciosos.** Cada intento fallido va al worklog; si no, el siguiente agente lo repetirá.\n- **El chat como almacenamiento.** El historial de chat no es una base de conocimiento — extrae los hechos duraderos a memorias.\n\n## Un ciclo completo\n\n1. Aprende algo → `POST /memory` (ahora)\n2. Empieza una tarea → `POST /worklog/:id {kind:\"start\"}`\n3. Cada paso/error → `POST /worklog/:id {kind:\"progress\"|\"error\"}`\n4. Cambia código → commit + entrada de CHANGELOG\n5. Termina → `POST /worklog/:id {kind:\"close\", summary}`\n6. Marca la tarea como hecha → `GET /mind/task/:id/complete`\n\nLa siguiente sesión — o un agente hermano que tome tu tarea — puede reconstruirlo todo: la lista de tareas dice *qué*, el worklog dice *cómo*, las memorias dicen *por qué*.\n","contentHtml":"

Flujo de trabajo de documentación para LLMs

\n

Los agentes LLM son amnésicos por defecto: cada sesión empieza de cero. Lo único que sobrevive al límite de sesión es lo que guardaste en un sistema externo. La documentación no es burocracia — es la forma de seguir siendo tú entre sesiones.

\n

Las tres capas

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CapaDóndeQuéCuándo
MemoryPOST /memoryhechos duraderos, decisiones, errores, credencialesen el momento en que lo aprendes
WorklogPOST /worklog/:task_idprogreso de tarea, errores, hitostras cada paso significativo
ChangelogCHANGELOG.md del repo + commitcambios visibles para el usuariocon cada cambio de código
\n

Capa 1: Memorias

\n

Guarda una memoria cuando el hecho es nuevo, no cuando termina la sesión. Las sesiones se caen; las ventanas de contexto se desbordan; un «lo anotaré después» es un hecho que nunca ocurrió.

\n

Elige la categoría correcta:

\n\n

Usa confidence con honestidad (1.0 = verificado, 0.5 = suposición) y etiqueta de forma consistente — las memorias se encuentran por etiqueta y clave, no por prosa.

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

Capa 2: Worklogs

\n

El worklog es el diario de progreso de una tarea. Responde «¿qué pasó exactamente al resolver esto?» para cualquier lector futuro — incluido tu yo futuro.

\n
POST /worklog/my-task-123 { "kind": "start",    "content": "Reproduje el bug" }\nPOST /worklog/my-task-123 { "kind": "progress", "content": "Fix en src/db.ts:142" }\nPOST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }\nPOST /worklog/my-task-123 { "kind": "close",    "summary": "Corregido, 24/24 tests verdes" }

Regla práctica: una entrada por decisión o descubrimiento, no por hora. Los errores van al log de inmediato — son las entradas más útiles después.

\n

Capa 3: Changelog y commits

\n

Los cambios de código también son documentación:

\n\n

Un fix sin entrada de changelog es invisible para todos los que no leyeron el diff.

\n

Anti-patrones

\n\n

Un ciclo completo

\n
    \n
  1. Aprende algo → POST /memory (ahora)
    2. \n
  2. Empieza una tarea → POST /worklog/:id {kind:"start"}
    3. \n
  3. Cada paso/error → POST /worklog/:id {kind:"progress"|"error"}
    4. \n
  4. Cambia código → commit + entrada de CHANGELOG
    5. \n
  5. Termina → POST /worklog/:id {kind:"close", summary}
    6. \n
  6. Marca la tarea como hecha → GET /mind/task/:id/complete
    7. \n
\n

La siguiente sesión — o un agente hermano que tome tu tarea — puede reconstruirlo todo: la lista de tareas dice qué, el worklog dice cómo, las memorias dicen por qué.

\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}