Skip to main content
Este documento define el proceso para cerrar correctamente una sesión de implementación con AI coding agents. El objetivo: que la siguiente persona (o tú mismo mañana) pueda retomar sin perder contexto.

Principio fundamental

Una sesión sin cierre es deuda de contexto. Cada sesión que termina sin documentar qué se hizo, qué cambió, y qué quedó pendiente le cuesta tiempo a la siguiente sesión. El cierre no es burocracia — es inversión.

1. Cuándo usar este protocolo

  • Al terminar una sesión de implementación de features
  • Al terminar una sesión de corrección de bugs que modificó comportamiento
  • Al terminar una sesión de gestión de cambios (protocolo CHG-XXX)
  • Al terminar una sesión de refactoring que afectó la arquitectura
NO es necesario para:
  • Sesiones exploratorias o de investigación sin cambios de código
  • Sesiones de solo lectura/análisis
  • Fix de typos o cambios cosméticos menores

2. El cierre en 3 fases


3. Fase A — La AI documenta

Pedirle a la AI que ejecute las siguientes actualizaciones. Usar este prompt o uno equivalente adaptado a la herramienta:

Prompt de cierre

SESSION_LOG.md — formato de entrada


4. Fase B — El humano verifica

Esta fase NO es delegable a la AI. El humano revisa lo que la AI documentó.

Checklist de verificación (5 puntos)

4.1 ¿El resumen de sesión es correcto?

Abrir docs/SESSION_LOG.md y verificar:
  • ¿La descripción refleja lo que realmente se hizo?
  • ¿Los archivos modificados son los correctos? (cruzar con git diff --name-only)
  • ¿Los pendientes están claros para alguien que no estuvo en la sesión?
Error común de la AI: Listar archivos que no se modificaron, u omitir archivos que sí cambiaron. Siempre cruzar con el diff de git.

4.2 ¿La documentación actualizada es precisa?

Para cada documento que la AI dice haber actualizado:
  • Abrir el documento y leer la sección modificada
  • ¿La información agregada es correcta? (no inventó features, no cambió datos existentes)
  • ¿Mantuvo el formato y tono del resto del documento?
Error común de la AI: Agregar información redundante, cambiar secciones que no debía tocar, o describir la implementación de forma imprecisa. Especial atención a números (endpoints, conteos de tests, versiones).

4.3 ¿Los anti-patrones son reales?

Si la AI agregó algo a “What NOT to Do” o “Gotchas”:
  • ¿Es un error real que ocurrió, o es una precaución genérica?
  • ¿La descripción es suficientemente específica para ser útil?
Regla: Solo agregar anti-patrones que realmente ocurrieron en esta sesión. No permitir que la AI agregue advertencias genéricas del tipo “NO usar eval()“.

4.4 ¿Los tests pasan?

  • Ejecutar la suite de tests completa (no solo los tests nuevos)
  • Si algún test falla, NO cerrar la sesión — corregir primero

4.5 ¿Quedó algo sin documentar?

Revisar mentalmente:
  • ¿Se tomó alguna decisión de arquitectura que no quedó escrita?
  • ¿Se descubrió algo sobre el comportamiento del sistema que otros deberían saber?
  • ¿Cambió algún flujo de usuario que debería reflejarse en el PRD o la guía de diseño?
Si la respuesta es sí a cualquiera, agregar manualmente antes de cerrar.

5. Fase C — El humano cierra

5.1 Commit de código + documentación

Hacer commit de todo junto (código + docs actualizados) para que el historial de git refleje qué cambio de código motivó qué cambio de docs.
Regla: El código y su documentación se commitean juntos. Nunca commitear código en un commit y docs en otro — pierdes la trazabilidad.

5.2 Sincronizar espejo en Notion (si aplica)

Actualizar el espejo de documentación en Notion con los cambios relevantes. No es necesario copiar todo — solo:
  • Estado de features (completado, en progreso, pendiente)
  • Decisiones de producto tomadas
  • Pendientes que el equipo debe conocer
Regla: Notion es el espejo para humanos, no la fuente de verdad técnica. Si hay conflicto entre lo que dice Notion y lo que dice el repo, el repo gana.

5.3 Cerrar cambios pendientes (si aplica)

Si la sesión completó un cambio del protocolo de gestión de cambios:
  • Verificar que el CHG-XXX en docs/changes/pending/ está marcado como completado
  • Mover resumen a docs/changes/CHANGE_LOG.md
  • Eliminar el archivo de pending/

6. SESSION_LOG.md — reglas del documento

Estructura del archivo

Reglas

  • Orden: sesión más reciente arriba (cronológico inverso)
  • Una entrada por sesión: no agrupar múltiples sesiones en una entrada
  • Formato consistente: usar siempre la plantilla de la sección 3
  • Limpieza: cuando el archivo supere ~50 entradas, archivar las más antiguas en docs/SESSION_LOG_ARCHIVE.md y mantener solo las últimas 20

Cuándo consultar el SESSION_LOG

Al iniciar una nueva sesión, la AI (o el humano) debería leer las últimas 2-3 entradas del SESSION_LOG para:
  • Saber qué se hizo en la sesión anterior
  • Retomar pendientes
  • No duplicar trabajo ya hecho
Tip: Agregar al AGENTS.md del proyecto:

7. División de responsabilidades


8. Modo rápido (sesiones cortas)

Para sesiones menores a 30 minutos o cambios muy pequeños, el protocolo completo puede ser excesivo. Usar este checklist reducido:
  • Tests pasan
  • Agregar entrada mínima al SESSION_LOG (1-2 líneas: qué se hizo + pendiente)
  • Commit con mensaje descriptivo
  • Si se descubrió un gotcha → agregar a “What NOT to Do”
No es necesario pedir a la AI que actualice toda la documentación si el cambio fue menor. Usar criterio.

9. Inicio de sesión (el complemento)

Este protocolo funciona en par con un ritual de inicio de sesión:
Agregar esto al AGENTS.md del proyecto para que la AI lo haga automáticamente.

10. Cómo usar este protocolo

Como skill de Claude Code

Copiar a .claude/skills/session-closure/SKILL.md. Claude lo cargará al detectar que la sesión está terminando o cuando le pidas cerrar.

Como referencia en AGENTS.md

Para herramientas agnósticas

Los principios (documentar qué se hizo, verificar, commitear junto) aplican sin importar la herramienta. El prompt de cierre se adapta al formato de cada una.

11. Checklist imprimible