El comando /speckit.implement

De las tareas al código

El comando /speckit.implement es la fase final del flujo SDD donde las decisiones técnicas se materializan en código funcional. Mientras que los artefactos anteriores (especificación, plan, tareas) son documentos que describen intenciones, /speckit.implement produce el resultado tangible: archivos de código, tests, configuraciones y documentación que conforman la feature.

El comando opera como un orquestador que lee el tasks.md y ejecuta cada tarea en el orden definido por las dependencias. No genera código de forma monolítica. En su lugar, descompone la implementación en unidades atómicas (una por tarea) que se ejecutan, verifican y confirman de forma independiente.

La implementación en SDD no es un acto creativo del agente IA. Es la ejecución metódica de un plan que ya ha sido revisado y validado. El agente tiene la libertad de decidir cómo implementar cada tarea, pero no qué implementar ni en qué orden.

Cómo ejecutar el comando

El comando se ejecuta en el chat del agente IA sin argumentos:

/speckit.implement

Al recibir el comando, el agente realiza las siguientes operaciones:

• 1. Localiza el tasks.md de la feature activa. Si no existe, indica que primero debe ejecutarse /speckit.tasks.

• 2. Carga los artefactos de referencia: lee el spec.md, plan.md, data-model.md, contracts/ y quickstart.md para tener el contexto completo de la feature.

• 3. Lee la constitución para aplicar los principios del proyecto durante la generación de código (por ejemplo, Test-First implica que los tests se escriben antes de la implementación de cada componente).

• 4. Ejecuta las tareas en orden, respetando las dependencias definidas en el tasks.md.

• 5. Marca cada tarea como completada ([x]) en el tasks.md tras su ejecución exitosa.

• 6. Realiza commits atómicos después de cada tarea o grupo de tareas paralelas.

flowchart LR
    TASKS["tasks.md"] --> CMD["/speckit.implement"]
    PLAN["plan.md"] --> CMD
    SPEC["spec.md"] --> CMD
    CONST["constitution.md"] --> CMD
    CMD --> CODE["Código generado"]
    CMD --> TESTS["Tests"]
    CMD --> COMMITS["Commits atómicos"]

El modelo de ejecución por subagentes

El aspecto más relevante de /speckit.implement es el modelo de aislamiento de contexto. En lugar de ejecutar todas las tareas en una única sesión acumulativa, el agente principal delega cada tarea a un subagente con contexto limpio.

El agente principal actúa como un director de proyecto:

• Lee la siguiente tarea pendiente del tasks.md.
• Crea un subagente con acceso al estado actual del repositorio.
• Le proporciona la descripción de la tarea, el spec.md y los artefactos relevantes.
• El subagente ejecuta la tarea, modifica los archivos necesarios y devuelve el control.
• El agente principal verifica el resultado, realiza el commit y pasa a la siguiente tarea.

flowchart TB
    MAIN["Agente principal<br>(orquestador)"] --> S1["Subagente 1<br>T001: Setup"]
    MAIN --> S2["Subagente 2<br>T002: Model"]
    MAIN --> S3["Subagente 3<br>T003: Service"]
    MAIN --> S4["Subagente 4<br>T004: Tests"]
    S1 -->|commit| MAIN
    S2 -->|commit| MAIN
    S3 -->|commit| MAIN
    S4 -->|commit| MAIN

Este modelo resuelve dos problemas documentados en la literatura de desarrollo con agentes IA:

Agent Amnesia: cuando una sesión se interrumpe, todo el progreso en memoria se pierde. Con commits atómicos por tarea, el progreso queda registrado en el repositorio. Si la sesión se interrumpe en la tarea T012, las tareas T001-T011 ya están committeadas y no es necesario repetirlas.

Context Pollution: en sesiones largas, las decisiones tempranas contaminan las decisiones posteriores. Un error de diseño en el minuto 5 se propaga a todo el código generado en los minutos siguientes. Con subagentes de contexto limpio, cada tarea empieza sin la carga del contexto acumulado. Si el subagente que implementa T007 comete un error, ese error no afecta al subagente que implementa T008.

Commits atómicos

Cada tarea completada produce un commit independiente con un mensaje descriptivo que referencia el task ID:

T004: Create CalendarEvent model in src/models/event.py
T005: Create EventShare model in src/models/share.py
T006: Configure database migrations in src/db/migrations/

Los commits atómicos proporcionan varios beneficios:

Rollback granular: si la tarea T012 introduce un bug, se puede revertir únicamente ese commit sin afectar al trabajo de T001-T011. Sin commits atómicos, un error tardío podría requerir deshacer horas de trabajo.

Historial legible: el historial de Git refleja directamente las tareas del tasks.md. Cualquier desarrollador puede trazar un commit específico hasta la tarea que lo originó, y desde allí hasta la user story y el requisito de negocio.

Puntos de verificación: los pre-commit hooks configurados en el proyecto (linters, type checkers, tests) se ejecutan en cada commit. Si el código generado por una tarea no pasa las validaciones, el commit se rechaza y el subagente debe corregir el problema antes de continuar.

Cada commit de /speckit.implement es un punto de verificación. Si los tests pasan tras el commit, la tarea está correctamente implementada. Si fallan, el error está aislado en esa tarea concreta.

Ejecución de tareas paralelas

Cuando el agente encuentra tareas marcadas con [P] en el tasks.md, puede ejecutarlas de forma concurrente mediante subagentes independientes. Cada subagente trabaja sobre archivos distintos, garantizando que no hay conflictos de escritura.

## Phase 2: Foundational

- [ ] T004 [P] Create CalendarEvent model
      in src/models/event.py
- [ ] T005 [P] Create EventShare model
      in src/models/share.py
- [ ] T006 [P] Create User model
      in src/models/user.py
- [ ] T007 Configure database migrations

En este ejemplo, el agente principal lanza tres subagentes simultáneamente para T004, T005 y T006. Cuando los tres completan su trabajo, el agente principal verifica los resultados, realiza los commits correspondientes y pasa a T007 (que depende de que los tres modelos existan).

La paralelización reduce el tiempo total de implementación. En proyectos donde las tareas paralelas representan un porcentaje significativo del total, el ahorro puede superar el 30% del tiempo de ejecución. No todos los agentes IA soportan esta capacidad de subagentes concurrentes, pero aquellos que sí lo hacen (como Claude Code) aprovechan directamente esta estructura del tasks.md.

Checkpoints durante la implementación

Los checkpoints definidos entre las fases del tasks.md se convierten en puntos de pausa durante la implementación. Cuando el agente alcanza un checkpoint, detiene la ejecución de tareas y ejecuta las verificaciones especificadas.

### Checkpoint: Foundational Verification
- [ ] All models have corresponding tests
- [ ] Database migrations run successfully
- [ ] Foreign key relationships are correct

Si las verificaciones del checkpoint pasan, el agente continúa con la siguiente fase. Si alguna verificación falla, el agente puede:

• Corregir automáticamente el problema si es un error menor (un test que falta, una importación incorrecta).
• Escalar al usuario si el problema requiere una decisión de diseño que no está cubierta por el plan.
• Detener la implementación si el fallo indica un problema estructural que afectaría a las fases posteriores.

Los checkpoints son el mecanismo que mantiene la calidad de la implementación a lo largo de las fases. Sin ellos, un error en Phase 2 podría pasar desapercibido hasta Phase 5, cuando el coste de corrección es mucho mayor.

Flujo completo de implementación

El proceso de implementación sigue un ciclo predecible para cada tarea:

flowchart TB
    READ["Leer siguiente<br>tarea pendiente"] --> DELEGATE["Delegar a<br>subagente"]
    DELEGATE --> EXEC["Subagente ejecuta<br>la tarea"]
    EXEC --> VERIFY["Verificar resultado<br>(tests, lint)"]
    VERIFY -->|Pasa| COMMIT["Commit atómico"]
    VERIFY -->|Falla| FIX["Corregir y<br>reintentar"]
    FIX --> VERIFY
    COMMIT --> MARK["Marcar tarea<br>como completada"]
    MARK --> CHECK{"Es<br>checkpoint?"}
    CHECK -->|Sí| CHECKPOINT["Ejecutar<br>verificaciones"]
    CHECK -->|No| READ
    CHECKPOINT -->|Pasa| READ
    CHECKPOINT -->|Falla| ESCALATE["Escalar o<br>corregir"]
    ESCALATE --> CHECKPOINT

Este flujo garantiza que cada paso de la implementación es verificable y reversible. El resultado final es un repositorio con un historial limpio de commits atómicos, donde cada commit corresponde a una tarea documentada en el tasks.md.

Reanudar implementaciones interrumpidas

Una de las ventajas del modelo de tareas con commits atómicos es la capacidad de reanudar la implementación tras una interrupción. Si la sesión del agente se interrumpe o el usuario necesita pausar el trabajo, el estado de progreso queda registrado en dos lugares:

• El tasks.md tiene las tareas completadas marcadas con [x] y las pendientes con [ ].
• El repositorio Git tiene los commits de las tareas completadas.

Al ejecutar /speckit.implement de nuevo, el agente detecta las tareas ya completadas y reanuda desde la primera tarea pendiente. No repite trabajo. Esta idempotencia es fundamental en implementaciones largas que pueden requerir múltiples sesiones con el agente.

Resuming implementation from T012.
Tasks T001-T011 already completed (11/25).
Continuing with Phase 3: US1 - Crear eventos.

Esta capacidad de reanudación también facilita la colaboración entre el agente IA y el equipo humano. Un desarrollador puede completar manualmente una tarea marcándola en el tasks.md y realizando el commit correspondiente. Cuando el agente retoma la implementación, reconoce ese trabajo y continúa con la siguiente tarea pendiente.