Lección 12 — Dejá un handoff limpio al final de cada sesión

Tu agente corre toda la tarde, modifica 20 archivos, commitea, la sesión termina. La sesión siguiente arranca y descubre inmediatamente: el build está roto, los tests en rojo, los archivos temporales de debug por todos lados, la feature list sin actualizar y el progreso completamente incierto. Los primeros 30 minutos se van solo en averiguar qué hizo realmente la sesión anterior.

Tanto OpenAI como Anthropic lo afirman con claridad: la fiabilidad a largo plazo depende de la disciplina operacional, no solo del éxito en una única ejecución. La calidad del estado al final de la sesión determina directamente la eficiencia de la siguiente.

Conceptos clave

• Clean state: el sistema satisface cinco condiciones al final de la sesión —el build pasa, los tests pasan, el progreso está registrado, no hay artefactos obsoletos y la ruta de arranque está disponible—. Que falte cualquiera significa que la sesión no está terminada.
• Integridad de sesión: análogo a las transacciones de base de datos. O se commitea completo dejando un clean state, o se hace rollback al último estado consistente. No hay término medio.
• Documento de calidad: un artefacto vivo que registra continuamente las calificaciones de calidad de cada módulo. No es una evaluación única, sino un rastreador que muestra si la base de código se fortalece o se debilita con el tiempo.
• Bucle de limpieza: una sesión de mantenimiento regular orientada a reducir sistemáticamente la entropía. No es una corrección de emergencia, son operaciones de rutina.
• Simplificación del harness: a medida que mejoran las capacidades del modelo, eliminar periódicamente los componentes que ya no son necesarios.
• Limpieza idempotente: las operaciones de limpieza producen el mismo resultado sin importar cuántas veces se ejecuten.

El crecimiento de la entropía es el estado por defecto

Las leyes de Lehman sobre la evolución del software nos dicen que los sistemas sometidos a cambios continuos aumentarán inevitablemente en complejidad a menos que se gestionen activamente. Esto es especialmente cierto con agentes: cada sesión introduce cambios, y sin limpieza al salir, la deuda técnica se acumula exponencialmente.

Un proyecto desarrollado con agentes durante 12 semanas:

Semana	Sin estrategia de limpieza	Con estrategia de limpieza
1	Build 100%, tests 100%, arranque 5 min	Build 100%, tests 100%, arranque 5 min
4	Build 95%, tests 92%, arranque 15 min	—
8	Build 82%, tests 78%, arranque 35 min	—
12	Build 68%, tests 61%, arranque 60+ min, 103 artefactos obsoletos	Build 97%, tests 95%, arranque 9 min, 11 artefactos obsoletos

Después de 12 semanas: 29 puntos porcentuales de diferencia en la tasa de build exitoso y 85% menos de tiempo de arranque de sesión nueva.

Las cinco dimensiones del clean state

flowchart TD
    S["Fin de sesión"] --> D1{"1. Build<br/>¿compila sin errores?"}
    D1 -->|No| F["Sesión NO terminada"]
    D1 -->|Sí| D2{"2. Tests<br/>¿pasan todos,<br/>incluidos los previos?"}
    D2 -->|No| F
    D2 -->|Sí| D3{"3. Progreso<br/>¿registrado en artefacto<br/>legible por máquina?"}
    D3 -->|No| F
    D3 -->|Sí| D4{"4. Artefactos<br/>¿sin temporales, logs de debug<br/>o código comentado?"}
    D4 -->|No| F
    D4 -->|Sí| D5{"5. Arranque<br/>¿la ruta estándar<br/>sigue disponible?"}
    D5 -->|No| F
    D5 -->|Sí| OK["Clean state<br/>sesión terminada"]

Dimensión de build: la sesión siguiente no debería tener que corregir errores de build primero.

Dimensión de tests: incluyendo los tests que existían antes de la sesión. La sesión es responsable de no romper la funcionalidad existente. Y debería verificarse en CI, no solo “funciona en mi máquina”.

Dimensión de progreso: subtareas completadas con sus criterios de aprobación, subtareas en progreso con su estado actual, subtareas aún no iniciadas. Buenos registros de progreso reducen entre 60% y 80% el tiempo de diagnóstico al inicio de la sesión.

Dimensión de artefactos: logs de debug, archivos temporales, código comentado, marcadores TODO. Todos aumentan la carga cognitiva para la sesión siguiente.

Dimensión de arranque: inicialización del entorno, carga de la base de código, adquisición de contexto, selección de tareas. Estas rutas no deben estar rotas.

”Limpiar después” significa nunca limpiar

La trampa mental más común es “no hay tiempo para limpiar esta sesión, lo hago la próxima”. Pero la sesión siguiente del agente no sabe qué dejaste atrás: ve un desorden de código y un estado incierto. Va a dedicar tiempo significativo a inferir qué partes son intencionales y cuáles temporales.

Peor todavía: cada sesión tiene sus propios objetivos. La sesión nueva está ahí para hacer trabajo nuevo, no para limpiar el desorden de la anterior. Va a ignorar el caos y empezar trabajo nuevo encima, introduciendo más caos sobre el caos.

Cómo hacerlo bien

1. Clean state como requisito de finalización

Definí explícitamente en el harness: finalización de sesión = la tarea pasa la verificación Y la verificación de clean state pasa.

## Checklist de salida de sesión
- [ ] El build pasa (npm run build)
- [ ] Todos los tests pasan (npm test)
- [ ] La feature list está actualizada
- [ ] No queda código de debug (console.log, debugger, TODO)
- [ ] La ruta de arranque estándar está disponible (npm run dev)

2. Estrategia de limpieza dual

Modo	Cuándo	Qué hace
Limpieza inmediata	Al final de cada sesión	Limpiar artefactos temporales de la sesión, actualizar el estado de la feature list, asegurar que build y tests pasen
Limpieza periódica	Semanal	Escaneo completo del sistema, problemas estructurales acumulados, actualizar documentos de calidad, correr tests de referencia para detectar desviaciones

3. Mantené un documento de calidad

# Documento de calidad

## Módulo de autenticación de usuario (Calidad: A)
- Verificación pasando: Sí
- Comprensible para el agente: Sí
- Estabilidad de tests: Estable
- Límites arquitectónicos: Conforme
- Convenciones de código: Seguidas

## Módulo de pagos (Calidad: C)
- Verificación pasando: Parcial (callback de pago sin testear)
- Comprensible para el agente: Difícil (lógica repartida en 3 archivos)
- Estabilidad de tests: Inestable (2 tests flaky)
- Límites arquitectónicos: Hay violaciones
- Convenciones de código: Parcialmente seguidas

Las sesiones nuevas leen este documento e inmediatamente saben dónde priorizar: corregí primero el módulo con la calificación más baja.

4. Simplificá periódicamente el harness

Una perspectiva importante de Anthropic: cada componente del harness existe porque el modelo no puede hacer algo de manera confiable por sí solo. Pero a medida que los modelos mejoran, esos supuestos quedan obsoletos. Una restricción esencial hace tres meses puede ser sobrecarga innecesaria hoy.

flowchart LR
    A["Elegí un componente<br/>del harness"] --> B["Snapshot del<br/>documento de calidad"]
    B --> C["Desactivalo<br/>temporalmente"]
    C --> D["Corré las tareas<br/>de benchmark"]
    D --> E{"¿Bajaron las<br/>calificaciones?"}
    E -->|No| F["Eliminalo<br/>permanentemente"]
    E -->|Sí| G["Restauralo o reemplazalo<br/>por una alternativa más liviana"]

Práctica recomendada: una vez por mes.

5. Las operaciones de limpieza deben ser idempotentes

# Operaciones de limpieza idempotentes
rm -f /tmp/debug-*.log        # -f evita el error si los archivos no existen
git checkout -- .env.local    # Restaura a un estado conocido
npm run test                  # Verifica que la limpieza no rompió nada

Caso del mundo real

Una aplicación Electron desarrollada con agentes durante 12 semanas, dos enfoques comparados:

Métrica en la semana 12	Sin estrategia	Con estrategia
Tasa de build exitoso	68%	97%
Tasa de tests exitosos	61%	95%
Arranque de sesión nueva	60+ min	9 min
Artefactos obsoletos	103	11

Ideas clave

• El clean state es condición necesaria para la finalización de la sesión, no limpieza opcional: es parte de la definición de terminado.
• Las cinco dimensiones son todas necesarias: build, tests, progreso, artefactos y arranque.
• Los documentos de calidad hacen rastreable la salud de la base de código: solo podés arreglar lo que sabés que se está degradando.
• Simplificá periódicamente el harness: eliminá las restricciones que dejaron de ser necesarias.
• “Limpiar después” equivale a nunca limpiar: el crecimiento de la entropía es el estado por defecto.

Ejercicios

1. Checklist de clean state: diseñá una checklist de salida para tu base de código que cubra las cinco dimensiones. Aplicala durante 5 sesiones consecutivas y registrá las violaciones por dimensión.
2. Comparación de referencia: usá un conjunto fijo de tareas con dos variantes de harness (con y sin requisitos de clean state). Compará tasa de finalización, cantidad de reintentos y tasa de escape de defectos.
3. Práctica de simplificación: elegí un componente del harness, desactivalo temporalmente y corré tareas de benchmark. Decidí si mantenerlo, eliminarlo o reemplazarlo.

Lecturas adicionales

• Clean Code — Robert C. Martin
• OpenAI: Harness Engineering
• Anthropic: Effective Harnesses for Long-Running Agents
• Programs, Life Cycles, and Laws of Software Evolution — Lehman

---

Anterior: Lección 11 — Hacé observable el runtime del agente · Siguiente: Lección 13 — Del prompting manual a los loops autónomos