Anatomía de tasks.md

Estructura general del archivo

El archivo tasks.md es el artefacto que conecta la planificación técnica con la implementación. Su estructura sigue un patrón predecible que el agente IA interpreta de forma mecánica durante la fase de implementación: lee la siguiente tarea pendiente, ejecuta la acción descrita, marca la tarea como completada y avanza a la siguiente.

Un tasks.md completo tiene varias secciones diferenciadas:

# Implementation Tasks: Crear eventos de calendario

**Feature**: 001-crear-eventos-calendario
**Spec**: specs/001-crear-eventos-calendario/spec.md
**Plan**: specs/001-crear-eventos-calendario/plan.md

## Implementation Strategy

MVP-first delivery. Phase 1 establishes project
infrastructure. Phase 2 creates shared entities.
Phases 3-5 implement user stories in priority order.
Phase 6 handles cross-cutting concerns.

## Phase 1: Setup
...

## Phase 2: Foundational
...

## Phase 3: User Story 1 - Crear eventos
...

## Dependencies & Execution Order
...

La cabecera vincula las tareas con la feature, la especificación y el plan. La sección Implementation Strategy resume la estrategia de entrega. Las fases contienen las tareas en sí. La sección de dependencias documenta el orden de ejecución y las relaciones entre tareas.

Anatomía de una tarea individual

Cada tarea sigue un formato compacto que codifica toda la información necesaria para su ejecución en una sola línea:

- [ ] T014 [US1] Implement event creation endpoint in src/api/routes/events.py

Este formato tiene cinco componentes obligatorios y dos opcionales:

Checkbox (- [ ]): representa el estado de la tarea. El agente marca - [x] al completarla. Este checkbox permite hacer seguimiento del progreso y, durante la regeneración del archivo, el agente preserva el estado de las tareas completadas.

Task ID (T014): identificador secuencial único con formato T seguido de un número de tres dígitos. La numeración es global dentro del archivo, no por fase. T001 es la primera tarea del proyecto, T025 es la vigésimo quinta, sin importar en qué fase se encuentre. Este identificador se utiliza en la sección de dependencias para referenciar tareas.

Marcador de paralelización ([P]): componente opcional que indica que la tarea puede ejecutarse en paralelo con otras tareas del mismo grupo que también llevan el marcador [P]. La ausencia de este marcador implica que la tarea es secuencial y debe completarse antes de iniciar la siguiente.

Etiqueta de user story ([US1]): componente obligatorio en las fases de user stories. Vincula la tarea con la user story que implementa. Las tareas de las fases Setup, Foundational y Polish no llevan esta etiqueta.

Descripción con file path: acción concreta en imperativo seguida de la ruta del archivo destino. La descripción debe ser lo suficientemente precisa para que el agente sepa qué hacer sin consultar otros documentos.

Cada tarea debe ser autocontenida: un agente IA con acceso al repositorio y a la descripción de la tarea debe poder completarla sin necesidad de contexto adicional.

El marcador [P] de paralelización

El marcador [P] es una de las características más relevantes del formato de tareas. Indica que varias tareas dentro del mismo grupo pueden ejecutarse simultáneamente sin conflictos, porque operan sobre archivos diferentes y no tienen dependencias de datos entre sí.

## 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
      in src/db/migrations/

En este ejemplo, las tareas T004, T005 y T006 llevan el marcador [P]. Esto significa que los tres modelos pueden crearse en cualquier orden o incluso al mismo tiempo. La tarea T007, sin marcador [P], es secuencial y depende de que los tres modelos existan previamente para configurar las migraciones.

La paralelización tiene implicaciones directas en el rendimiento de la implementación. En un escenario con agentes IA que soporten subagentes (como Claude Code con su sistema de tareas), las tareas paralelas se delegan a subagentes independientes que trabajan de forma concurrente. Cada subagente recibe contexto limpio, opera sobre su archivo asignado y confirma los cambios antes de devolver el control al agente principal.

flowchart TB
    subgraph Paralelo["Tareas paralelas"]
        T4["T004 [P]<br>CalendarEvent model"]
        T5["T005 [P]<br>EventShare model"]
        T6["T006 [P]<br>User model"]
    end
    subgraph Secuencial["Tarea secuencial"]
        T7["T007<br>Database migrations"]
    end
    T4 --> T7
    T5 --> T7
    T6 --> T7

No todas las tareas dentro de una fase son candidatas a paralelización. Para que dos tareas sean paralelas deben cumplir dos condiciones: operar sobre archivos distintos y no tener dependencias de datos entre sí. Si la tarea de crear el modelo EventShare necesita una referencia al modelo CalendarEvent (foreign key), ambas tareas no pueden ser paralelas, aunque operen sobre archivos diferentes.

Dependencias entre tareas

La sección Dependencies & Execution Order del tasks.md documenta las relaciones de precedencia entre tareas. Esta sección no es un simple listado, sino un grafo de dependencias que el agente utiliza para determinar qué tareas están disponibles para ejecución en cada momento.

## Dependencies & Execution Order

### Story Completion Order
1. Phase 1 (Setup): T001-T003
2. Phase 2 (Foundational): T004-T007
   Blocked by: Phase 1
3. Phase 3 (US1 - Crear eventos): T008-T015
   Blocked by: Phase 2
4. Phase 4 (US2 - Exportar calendario): T016-T020
   Blocked by: Phase 2
5. Phase 5 (Polish): T021-T025
   Blocked by: Phase 3, Phase 4

### Cross-phase Dependencies
- T012 (event validation) requires T004 (event model)
- T016 (export service) requires T006 (user model)
- T021 (API docs) requires T012, T016 (all endpoints)

Las dependencias se definen en dos niveles:

Dependencias entre fases: cada fase se marca como bloqueada por las fases previas que deben completarse. Phase 3 no puede comenzar hasta que Phase 2 esté completa. Phase 5 (Polish) no puede comenzar hasta que todas las fases de user stories estén completas.

Dependencias entre tareas individuales: dentro de las fases o entre fases, algunas tareas dependen de otras concretas. La tarea de implementar el servicio de validación de eventos (T012) depende de que exista el modelo de evento (T004), aunque ambas estén en fases diferentes.

Validación del grafo de dependencias

El agente valida automáticamente el grafo de dependencias al generar el tasks.md. Esta validación detecta cuatro tipos de problemas:

Dependencias circulares: si T005 depende de T012 y T012 depende de T008 que a su vez depende de T005, existe un ciclo que hace imposible la ejecución. El agente detecta estos ciclos mediante un recorrido en profundidad del grafo y detiene la generación hasta que se resuelvan.

Tareas huérfanas: tareas que no tienen dependencias ni son dependencia de ninguna otra. Podrían indicar que no pertenecen a la fase correcta o que les falta una conexión con el resto del trabajo.

Violaciones de orden entre fases: si una tarea de Phase 3 depende de una tarea de Phase 4, existe una violación de orden. Las fases anteriores no pueden depender de fases posteriores.

Inversiones de prioridad: si la user story de mayor prioridad (US1) depende de tareas de una user story de menor prioridad (US3), la priorización podría ser incorrecta.

DEPENDENCY GRAPH ANALYSIS

Total Tasks:      25
Circular Deps:    None              OK
Orphan Tasks:     None              OK
Critical Path:    6 tasks deep
Phase Boundaries: Valid             OK
Story Independence: Yes             OK

Parallel Opportunities: 4 groups
Estimated Parallelism: 35% speedup

Checkpoints de validación

Entre las fases del tasks.md, el agente IA puede insertar checkpoints de validación que actúan como puntos de control antes de avanzar a la siguiente fase. Estos checkpoints verifican que el trabajo completado hasta ese momento cumple con los criterios mínimos de calidad.

## Phase 2: Foundational

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

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

Un checkpoint típico verifica:

• Que los tests asociados a las tareas de la fase pasan correctamente.
• Que las integraciones configuradas en la fase funcionan (conexión a base de datos, APIs externas).
• Que la estructura del proyecto se ajusta a lo definido en el plan.md.
• Que el código generado es consistente con la constitución del proyecto.

Los checkpoints son especialmente importantes cuando la implementación la ejecuta un agente IA. Sin checkpoints, el agente podría construir las cinco fases secuencialmente y descubrir al final que un error en Phase 2 (un modelo con una columna mal definida) invalidó todo el trabajo posterior. Con checkpoints, el error se detecta al finalizar Phase 2, antes de invertir tiempo en las fases siguientes.

Los checkpoints son el equivalente a ejecutar tests después de cada sprint. No ralentizan la implementación de forma significativa, pero detectan problemas antes de que se propaguen a fases posteriores.

Ejemplo completo de tasks.md

Un tasks.md real combina todos los elementos descritos en un documento coherente. Este ejemplo corresponde a una feature de creación y exportación de eventos de calendario:

# Implementation Tasks: Crear eventos de calendario

**Feature**: 001-crear-eventos-calendario
**Spec**: specs/001/spec.md
**Plan**: specs/001/plan.md

## Implementation Strategy

MVP-first. Phase 1 sets up infrastructure.
Phase 2 creates shared data models.
Phase 3 implements event creation (P1).
Phase 4 implements calendar export (P2).
Phase 5 handles documentation and polish.

## Phase 1: Setup

- [ ] T001 Create project structure per plan
- [ ] T002 [P] Install dependencies from
      quickstart.md
- [ ] T003 [P] Configure environment variables
      in .env.example

## Phase 2: Foundational

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

### Checkpoint: Models Verification
- All models pass schema validation
- Migrations execute without errors

## Phase 3: US1 - Crear eventos (P1)

- [ ] T007 [US1] Implement event creation
      service in src/services/event_service.py
- [ ] T008 [US1] [P] Create POST /api/events
      endpoint in src/api/routes/events.py
- [ ] T009 [US1] [P] Create GET /api/events
      endpoint in src/api/routes/events.py
- [ ] T010 [US1] Add request validation
      in src/api/validators/event_validator.py
- [ ] T011 [US1] Write tests for event CRUD
      in tests/test_events.py

### Checkpoint: US1 Verification
- Event creation returns 201 with valid data
- Event validation rejects invalid date ranges
- All tests pass

## Phase 4: US2 - Exportar calendario (P2)

- [ ] T012 [US2] Implement icalendar generation
      in src/services/export_service.py
- [ ] T013 [US2] Create GET /api/events/export
      endpoint in src/api/routes/export.py
- [ ] T014 [US2] Implement share token generation
      in src/services/share_service.py
- [ ] T015 [US2] Write tests for export
      in tests/test_export.py

## Phase 5: Polish

- [ ] T016 Generate API documentation
- [ ] T017 Add error handling middleware
      in src/api/middleware/error_handler.py
- [ ] T018 Configure CI pipeline in .github/

## Dependencies & Execution Order

Phase 1 -> Phase 2 -> Phase 3, Phase 4 -> Phase 5
Phase 3 and Phase 4 can run in parallel after
Phase 2 completes.

Este ejemplo ilustra cómo los componentes del tasks.md trabajan en conjunto: las fases proporcionan estructura, los task IDs permiten referenciación, los marcadores [P] habilitan la paralelización, las etiquetas [US] mantienen la trazabilidad con los requisitos, y los checkpoints verifican la calidad entre fases.

Relación con la implementación

El archivo tasks.md es el artefacto de entrada principal para el comando /speckit.implement. Durante la implementación, el agente lee el tasks.md y ejecuta cada tarea en orden, respetando las dependencias y aprovechando las oportunidades de paralelización.

La calidad del tasks.md determina en gran medida la calidad de la implementación. Un tasks.md con descripciones vagas produce código ambiguo. Un tasks.md con rutas de archivo incorrectas genera archivos en ubicaciones inesperadas. Un tasks.md con dependencias mal definidas produce errores de compilación porque se intenta usar un módulo que aún no existe.

Por esta razón, la revisión del tasks.md antes de lanzar la implementación es una práctica recomendada. El equipo puede verificar que las fases son coherentes, que las dependencias reflejan la realidad técnica del proyecto, y que cada tarea tiene suficiente detalle para producir el código esperado.