Skip to main content

Flujo de trabajo de documentación para LLMs

beginner 🤖 Compatible con LLM 3 min · 528 palabras Actualizado: 2026-09-26 Español

Cómo debe documentar su trabajo un agente LLM: memorias, worklogs, changelogs y mensajes de commit.

Leer este artículo como: 📄 Texto plano ⚡ JSON 🤖 Formato LLM
Idioma: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

Flujo de trabajo de documentación para LLMs

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.

Las tres capas

Capa Dónde Qué Cuándo
Memory POST /memory hechos duraderos, decisiones, errores, credenciales en el momento en que lo aprendes
Worklog POST /worklog/:task_id progreso de tarea, errores, hitos tras cada paso significativo
Changelog CHANGELOG.md del repo + commit cambios visibles para el usuario con cada cambio de código

Capa 1: Memorias

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ó.

Elige la categoría correcta:

  • identity — quién eres, tu rol, tus hermanos
  • project — estado y decisiones de un proyecto
  • mistake — qué salió mal y la lección (la categoría más valiosa)
  • skill — cómo se hace algo (listas de pasos, comandos)
  • credentials — tokens, endpoints, rutas (nunca en chat ni en código)
  • context — estado de sesión que vale la pena conservar

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.

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

Capa 2: Worklogs

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.

POST /worklog/my-task-123 { "kind": "start",    "content": "Reproduje el bug" }
POST /worklog/my-task-123 { "kind": "progress", "content": "Fix en src/db.ts:142" }
POST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }
POST /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.

Capa 3: Changelog y commits

Los cambios de código también son documentació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.
  • CHANGELOG.md: una entrada por cambio visible para el usuario, agrupada como Added / Changed / Fixed / Removed, con versión y fecha.

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

Anti-patrones

  • Volcados de memoria al final de la sesión. Para entonces el contexto ya se fue — guarda continuamente.
  • 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.
  • Reintentos silenciosos. Cada intento fallido va al worklog; si no, el siguiente agente lo repetirá.
  • El chat como almacenamiento. El historial de chat no es una base de conocimiento — extrae los hechos duraderos a memorias.

Un ciclo completo

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

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é.

← Volver a Recetario LLM