Lección 06 — Inicializá antes de cada sesión del agente

Iniciás una sesión nueva y decís “agregá una funcionalidad de búsqueda”. El agente salta directamente a codificar, con entusiasmo admirable. Después de 20 minutos descubre que el framework de pruebas no está configurado correctamente y dedica otros 10 a arreglarlo; después el formato del script de migración está mal y hay que ajustarlo. La funcionalidad de búsqueda eventualmente se agrega, pero la mayor parte del tiempo se fue en “averiguar cómo funciona este proyecto” en lugar de escribir la búsqueda.

El mejor enfoque: antes de dejar que el agente empiece a trabajar, usá una fase separada para preparar el entorno base, hacer pasar los comandos de verificación y entender la estructura del proyecto. Es como construir una casa: no volcás los cimientos y levantás paredes simultáneamente.

Cimientos y paredes: dos trabajos distintos

La inicialización y la implementación tienen objetivos de optimización completamente diferentes:

Fase	Optimiza para	Salida
Inicialización	Maximizar la fiabilidad y eficiencia de toda la implementación posterior	Infraestructura
Implementación	Maximizar la cantidad y calidad de funcionalidades verificadas	Código

Cuando las mezclás, el agente enfrenta un problema de optimización multiobjetivo. Sin una priorización explícita, tiende naturalmente a escribir código —porque es una salida directamente visible— mientras sacrifica la infraestructura, cuyo valor solo se manifiesta en sesiones posteriores.

El ciclo de vida de la inicialización

flowchart TD
    START["Proyecto nuevo o<br/>sesión inicial"] --> I1["1. Entorno ejecutable<br/>dependencias instaladas y bloqueadas"]
    I1 --> I2["2. Framework de pruebas verificable<br/>al menos un test de ejemplo pasa"]
    I2 --> I3["3. Contrato de bootstrap<br/>comandos, estado, estructura"]
    I3 --> I4["4. Desglose de tareas<br/>lista ordenada con criterios de aceptación"]
    I4 --> I5["5. Commit de checkpoint limpio"]
    I5 --> GATE{"¿Se cumplen las<br/>4 condiciones?"}
    GATE -->|No| I1
    GATE -->|Sí| IMPL["Fase de implementación<br/>sesión 2 en adelante"]
    IMPL --> IMPL

Qué pasa cuando los mezclás

Los cimientos no se asientan. El agente gasta el 80% de su esfuerzo en código de funcionalidades y el 20% configurando infraestructura al pasar. El framework de pruebas está configurado pero nunca verificado, las reglas de lint están puestas pero son demasiado laxas, no se creó ningún archivo de progreso. Estos defectos no se notan en la primera sesión —el agente todavía recuerda lo que hizo— pero salen a la luz en la segunda.

Acumulación no verificada. El código escrito antes de que el framework de pruebas esté configurado es código sin verificación. Cuando finalmente volvés para agregarle tests, podés descubrir que el diseño estaba mal desde el principio.

Presupuesto de sesión desperdiciado. El trabajo de inicialización consume presupuesto significativo, dejando menos para la implementación real. La primera sesión completa la mitad de las funcionalidades y la segunda tiene que empezar de nuevo a entender el proyecto.

Minas de suposiciones implícitas. Las decisiones que el agente toma durante la inicialización —qué framework de pruebas, cómo organizar directorios, gestión de dependencias— si no se registran explícitamente, las sesiones posteriores no pueden entenderlas. Peor: pueden tomar decisiones contradictorias.

La investigación de Anthropic sobre desarrollo de aplicaciones de larga duración recomienda explícitamente separar la inicialización de la implementación. Sus datos: los proyectos con una fase de inicialización dedicada mostraron 31% más de tasa de completitud de funcionalidades en escenarios de múltiples sesiones. El tiempo invertido en la fase de inicialización se recupera completamente en las siguientes 3-4 sesiones.

Conceptos clave

• Fase de inicialización: la primera fase del ciclo de vida del agente. Sin implementación de funcionalidades, solo estableciendo prerrequisitos. La salida no es código, es infraestructura.
• Contrato de bootstrap: las condiciones bajo las cuales un proyecto puede ser operado sin ambigüedad por una sesión nueva: puede iniciar, puede probar, puede ver el progreso, puede retomar los siguientes pasos. Cuatro condiciones, todas requeridas.
• Arranque en frío vs arranque en caliente: el frío parte de un directorio vacío donde el agente debe adivinar la estructura; el caliente parte de una plantilla o proyecto existente donde la infraestructura ya está.
• Preparación para entrega: el proyecto está en un estado, en cualquier momento dado, donde un agente nuevo puede tomar el control solo con el contenido del repositorio.
• Tiempo hasta la primera verificación: el tiempo desde el inicio del proyecto hasta que el primer punto de funcionalidad pasa la verificación. Métrica central de eficiencia de inicialización.
• Usabilidad posterior: la proporción de sesiones posteriores que pueden ejecutar tareas exitosamente sin depender de conocimiento implícito. Es la mejor medida de la calidad de la inicialización.

Cómo hacer bien la inicialización

Tratá la inicialización como una fase dedicada. La primera sesión solo hace inicialización: nada de código de funcionalidades de negocio.

1. Entorno ejecutable

El proyecto arranca, las dependencias están instaladas y bloqueadas, sin problemas de entorno.

2. Framework de pruebas verificable

Al menos una prueba de ejemplo pasa. Esto demuestra que el framework en sí está correctamente configurado.

3. Documento de contrato de bootstrap

# Contrato de inicialización

## Comandos de arranque
- Instalar dependencias: `make setup`
- Levantar servidor de desarrollo: `make dev`
- Correr tests: `make test`
- Verificación completa: `make check`

## Estado actual
- Todas las dependencias instaladas y bloqueadas
- Framework de pruebas configurado (Vitest + React Testing Library)
- Test de ejemplo pasando (1/1)
- Reglas de lint configuradas (ESLint + Prettier)

## Estructura del proyecto
- src/            — Código fuente
- src/components/ — Componentes React
- src/api/        — Cliente de API
- tests/          — Archivos de test

4. Desglose de tareas

Dividí todo el proyecto en una lista ordenada, cada una con criterios de aceptación claros:

# Desglose de tareas

## Tarea 1: Bases de autenticación de usuario
- Implementar middleware de auth JWT
- Agregar endpoints de login/registro
- Aceptación: `pytest tests/test_auth.py` todo en verde

## Tarea 2: Página de perfil de usuario
- Implementar CRUD de perfil
- Agregar formulario de edición
- Aceptación: `pytest tests/test_profile.py` todo en verde

5. Commit de git como punto de control

Después de completar la inicialización, commiteá un checkpoint limpio. Todo el trabajo posterior arranca desde ahí.

Estrategia de arranque en caliente

No empieces desde un directorio vacío. Usá una plantilla de proyecto para preestablecer la estructura de directorios estándar, la configuración de dependencias y el framework de pruebas. Integrá los pasos comunes de inicialización en la plantilla, dejando solo el trabajo específico del proyecto.

Criterios de finalización de la inicialización

No es “cuánto código se escribió”, sino si se cumplen las cuatro condiciones del contrato de bootstrap:

## Checklist de aceptación de inicialización
- [ ] `make setup` tiene éxito desde cero
- [ ] `make test` tiene al menos un test pasando
- [ ] Una sesión de agente nueva puede responder "cómo ejecutar" y "cómo verificar"
      solo con el contenido del repo
- [ ] Existe archivo de desglose de tareas con al menos 3 tareas
- [ ] Todo commiteado en git

Ejemplo del mundo real

Dos enfoques de inicialización para un proyecto frontend de React:

Enfoque mixto (verter cimientos y construir paredes a la vez): el agente creó el scaffolding e implementó la primera funcionalidad en la sesión 1. Al final, el repositorio tenía código ejecutable pero sin documentación explícita de comandos, sin archivo de seguimiento de progreso y sin desglose de tareas. La sesión 2 dedicó ~20 minutos a inferir la estructura del proyecto, el framework de pruebas y el proceso de build.

Inicialización dedicada (cimientos primero): la sesión 1 solo inicializó —estructura desde plantilla, framework de pruebas configurado, test de ejemplo verificado, contrato de bootstrap, desglose de tareas y commit de checkpoint—. El tiempo de reconstrucción de la sesión 2 fue menos de 3 minutos.

Comparación del ciclo completo: el tiempo total de reconstrucción del enfoque mixto (a través de todas las sesiones) fue ~60% mayor que el de inicialización dedicada. Los 20 minutos extra invertidos se recuperaron varias veces.

Ideas clave

• La inicialización y la implementación tienen objetivos de optimización diferentes; mezclarlas arrastra a las dos hacia abajo.
• La salida de la inicialización no es código, es infraestructura: entorno ejecutable, pruebas verificables, contrato de bootstrap y desglose de tareas.
• Validá con las cuatro condiciones del contrato: puede iniciar, puede probar, puede ver el progreso, puede retomar los siguientes pasos.
• El arranque en caliente supera al frío. Usá plantillas para preestablecer infraestructura estandarizada.
• El tiempo invertido en inicialización se recupera en las siguientes 3-4 sesiones. No es un costo extra, es una inversión inicial.

Ejercicios

1. Diseño de contrato de bootstrap: escribí un contrato completo para un proyecto tuyo. Después abrí una sesión de agente nueva, mostrale solo el repositorio y pedile que inicie el proyecto, corra los tests y entienda el progreso. Cada problema que encuentre corresponde a una cláusula faltante.
2. Experimento comparativo: elegí un proyecto nuevo de complejidad moderada. Enfoque A: el agente inicializa e implementa a la vez. Enfoque B: una sesión dedicada a inicializar, implementación desde la sesión 2. Después de 4 sesiones, compará tiempo hasta la primera verificación, costo de reconstrucción y tasa de completitud.
3. Checklist de aceptación: diseñá una checklist para tu proyecto y hacé que una sesión nueva ejecute cada elemento. Los que fallan son donde tu harness necesita fortalecerse.

Lecturas adicionales

• Anthropic: Effective Harnesses for Long-Running Agents
• OpenAI: Harness Engineering
• Infrastructure as Code — Martin Fowler
• SWE-agent: Agent-Computer Interfaces

---

Anterior: Lección 05 — Mantené vivo el contexto entre sesiones · Siguiente: Lección 07 — Definí límites claros para las tareas