Implementación por fases

El problema de la saturación de contexto

Los agentes IA operan con una ventana de contexto finita. Cada instrucción enviada, cada archivo leído y cada línea de código generada consume parte de esa ventana. En implementaciones sencillas (5-10 tareas), el agente completa todo el trabajo dentro de una sola sesión sin problemas. En features complejas (20-40 tareas), la ventana de contexto se agota antes de completar todas las tareas.

Cuando un agente IA alcanza los límites de su ventana de contexto, su rendimiento se degrada de forma predecible:

• Comienza a olvidar decisiones tomadas al principio de la sesión.
• Genera código que contradice lo que ya ha implementado en fases anteriores.
• Pierde la referencia a convenciones de nombrado, estructura de directorios y patrones que estaba siguiendo.
• En casos extremos, empieza a descartar información relevante (bugs descubiertos, TODOs pendientes) para liberar espacio en el contexto.

La investigación en implementación con agentes IA muestra que las tareas que operan sobre un solo archivo alcanzan tasas de acierto del 87%, mientras que las implementaciones multi-archivo en sesiones largas caen por debajo del 20%. La diferencia se explica por la pérdida de contexto arquitectónico a lo largo de la sesión.

La implementación por fases resuelve este problema dividiendo el trabajo en segmentos que caben en la ventana de contexto del agente, con puntos de corte claros y verificaciones de integridad entre segmentos.

Cuándo aplicar implementación por fases

No todas las features requieren implementación por fases. El patrón es necesario cuando se cumplen una o más de estas condiciones:

La feature tiene más de 15-20 tareas: un tasks.md con 25+ tareas probablemente exceda la ventana de contexto del agente si se intenta ejecutar de forma continua. La implementación por fases divide el trabajo en bloques de 5-10 tareas.

La implementación supera los 30 minutos de ejecución continua: sesiones largas aumentan el riesgo de degradación del contexto. Cada 20-30 minutos, el agente pierde un porcentaje de las decisiones que tomó al inicio.

La feature toca múltiples dominios del sistema: una feature que modifica modelos de datos, servicios, endpoints, frontend y configuración de infraestructura implica que el agente debe mantener en contexto la totalidad de la arquitectura. Dividir por dominios reduce la carga cognitiva.

El equipo necesita verificación humana entre pasos: en features críticas, el equipo puede necesitar revisar el código generado antes de que el agente continúe con las fases siguientes.

flowchart TB
    EVAL{"La feature tiene<br>más de 15 tareas?"}
    EVAL -->|Sí| FASES["Implementación<br>por fases"]
    EVAL -->|No| EVAL2{"¿La ejecución superará<br>30 minutos?"}
    EVAL2 -->|Sí| FASES
    EVAL2 -->|No| EVAL3{"Toca múltiples<br>dominios?"}
    EVAL3 -->|Sí| FASES
    EVAL3 -->|No| DIRECTA["Implementación<br>directa"]

Cómo dividir la implementación

La división de la implementación sigue las fases del tasks.md como unidad natural de corte. Cada fase del tasks.md se convierte en una sesión de implementación independiente con su propio contexto limpio.

Estrategia de división por fases

La forma más directa de dividir la implementación es indicar al agente que ejecute una fase a la vez:

/speckit.implement

Ejecuta solo Phase 1 (Setup) y Phase 2
(Foundational). Detente después del
checkpoint de Phase 2.

Tras completar las fases indicadas y verificar los resultados, se inicia una nueva sesión para las fases siguientes:

/speckit.implement

Continua desde Phase 3 (US1 - Crear eventos).
Las fases 1 y 2 ya están completadas.

El agente detecta las tareas completadas en el tasks.md y en el historial de Git, por lo que no repite trabajo. Esta estrategia mantiene el contexto fresco para cada bloque de fases.

Estrategia de división por user stories

En features con muchas user stories, cada story puede implementarse como una sesión independiente:

/speckit.implement

Implementa solo las tareas de US1 (Phase 3).
Asume que Phase 1 y Phase 2 ya están
completadas.

Esta estrategia es útil cuando las user stories son independientes entre sí (no comparten servicios ni endpoints). Cada sesión se centra en una user story completa, desde los modelos hasta los tests, produciendo un incremento funcional verificable.

Estrategia de división por capas

En proyectos con separación frontend/backend, la división por capas permite implementar primero el backend completo y después el frontend:

Sesion 1: Implementa todos los modelos,
servicios y endpoints (backend).

Sesion 2: Implementa todos los componentes
de UI, páginas y estilos (frontend).

Esta estrategia es especialmente efectiva cuando el backend y el frontend tienen stacks tecnológicos diferentes (Python/FastAPI para el backend, TypeScript/React para el frontend). Cada sesión trabaja con un solo ecosistema de herramientas, reduciendo la carga de contexto.

Contexto limpio entre sesiones

El beneficio principal de la implementación por fases es que cada sesión comienza con un contexto limpio. El agente no arrastra las decisiones, errores ni suposiciones de la sesión anterior. Su único conocimiento proviene de:

• El tasks.md actualizado, con las tareas completadas marcadas.
• El código en el repositorio, que refleja el trabajo de sesiones anteriores.
• Los artefactos del plan (spec.md, plan.md, contracts/), que proporcionan el contexto de diseño.

flowchart TB
    subgraph S1["Sesión 1"]
        T1["T001-T006<br>Setup + Foundational"]
        C1["Commit + Checkpoint"]
    end
    subgraph S2["Sesión 2"]
        T2["T007-T011<br>User Story 1"]
        C2["Commit + Checkpoint"]
    end
    subgraph S3["Sesión 3"]
        T3["T012-T018<br>User Story 2 + Polish"]
        C3["Commit final"]
    end
    S1 -->|"Contexto limpio<br>+ tasks.md actualizado"| S2
    S2 -->|"Contexto limpio<br>+ tasks.md actualizado"| S3

Cada sesión lee el estado actual del repositorio sin la carga de la conversación previa. Si la sesión 1 tuvo un debate extenso sobre qué ORM utilizar (SQLAlchemy vs. Tortoise), ese contexto no ocupa espacio en la ventana de la sesión 2. La sesión 2 simplemente lee el código generado con SQLAlchemy y continúa el trabajo.

Verificación entre fases

El punto de corte entre sesiones es un momento natural de verificación. Antes de iniciar la siguiente sesión, el equipo puede revisar el trabajo completado:

Ejecutar los tests: comprobar que todas las tareas de la fase actual producen código que pasa los tests definidos en el checkpoint.

pytest tests/ -v --tb=short

Revisar el código generado: leer los archivos creados o modificados para verificar que siguen las convenciones del proyecto y la constitución.

Validar la integración: si la fase incluye conexiones a servicios externos (base de datos, APIs de terceros), verificar que las integraciones funcionan con datos reales, no solo con mocks.

Ejecutar /speckit.analyze: el comando de análisis puede ejecutarse en cualquier momento para detectar desalineaciones entre la especificación, el plan y las tareas completadas.

La verificación entre fases es el punto donde el equipo humano ejerce control sobre la implementación automatizada. No se trata de desconfiar del agente, sino de detectar desviaciones antes de que se acumulen.

Si la verificación detecta problemas, el equipo tiene varias opciones:

• Corregir manualmente el código y marcar las tareas como completadas.
• Ejecutar de nuevo la fase problemática con instrucciones adicionales para el agente.
• Ajustar el tasks.md para modificar las tareas de fases futuras en función de lo aprendido.

El patrón backpressure

La implementación por fases puede complementarse con el patrón backpressure, que utiliza pre-commit hooks para imponer controles de calidad automáticos en cada commit del agente.

El concepto es sencillo: se configuran hooks que ejecutan linters, type checkers y tests antes de permitir cada commit. Si el código generado por el agente no pasa estas validaciones, el commit se rechaza y el agente debe corregir el problema.

pre-commit hook:
  - typecheck (mypy/pyright)
  - lint (ruff/eslint)
  - test (pytest/vitest)

El backpressure actúa como un freno automático que impide que el código defectuoso entre al repositorio. Sin este mecanismo, un agente IA podría commitear código que compila pero no pasa los tests, acumulando deuda técnica que se descubre más tarde.

Combinado con la implementación por fases, el backpressure garantiza que cada sesión produce código que cumple los estándares de calidad del proyecto. Al finalizar cada fase, el repositorio contiene exclusivamente código validado.

Resultados prácticos

La implementación por fases produce resultados medibles en proyectos reales:

Rollback granular: si una sesión produce código defectuoso, se puede revertir solo esa sesión. Los commits de sesiones anteriores permanecen intactos. Un proyecto con 25 tareas dividido en 4 sesiones tiene 4 puntos de rollback en lugar de uno solo.

Transparencia del progreso: el tasks.md actualizado muestra exactamente cuántas tareas están completadas, cuántas quedan pendientes y en qué fase se encuentra la implementación. El equipo puede estimar el tiempo restante basándose en el ritmo de las sesiones anteriores.

Colaboración humano-agente: entre sesiones, el equipo humano puede intervenir. Un desarrollador puede completar una tarea manualmente si el agente tuvo dificultades con ella. Puede ajustar el plan si las sesiones anteriores revelaron que una decisión técnica no era la correcta. Esta flexibilidad hace que la implementación por fases sea compatible con equipos que combinan trabajo manual y automatizado.

La división en fases no es un overhead. Es una inversión que previene la forma más costosa de error en implementaciones con agentes IA: descubrir al final de una sesión larga que el agente perdió contexto en el minuto 15 y todo el código generado desde ese punto es inconsistente.