Artefactos del plan

El directorio de planificación

Cuando se ejecuta /speckit.plan, el agente no genera un único archivo. Produce un conjunto de artefactos que cubren diferentes aspectos de la planificación técnica. Cada artefacto tiene un propósito específico y será consumido por las fases posteriores del flujo SDD (tareas e implementación).

Todos los artefactos se generan dentro del directorio de la feature activa, junto al spec.md que ya existía:

specs/001-crear-eventos-calendario/
├── spec.md              # Generado por /speckit.specify
├── plan.md              # Plan de implementación
├── research.md          # Investigación técnica
├── data-model.md        # Modelo de datos
├── quickstart.md        # Guía de arranque rápido
├── contracts/           # Contratos de API
│   └── api-spec.json
├── checklists/
│   └── requirements.md
└── tasks.md             # Generado después por /speckit.tasks

Los artefactos de planificación son documentos intermedios que conectan los requisitos de negocio (spec.md) con las tareas ejecutables (tasks.md). Cada uno reduce un tipo concreto de incertidumbre técnica.

La generación de estos artefactos se organiza internamente en dos fases: Phase 0 (investigación) y Phase 1 (diseño técnico). Phase 0 produce el research.md. Phase 1 produce el plan.md, data-model.md, contracts/ y quickstart.md.

research.md: la investigación técnica

El archivo research.md es el primer artefacto que genera el comando, correspondiente a la Phase 0 del proceso de planificación. Su función es documentar la investigación que el agente IA realiza antes de tomar decisiones de diseño.

El contenido de research.md varía según la complejidad de la feature, pero habitualmente incluye:

Análisis de dependencias: el agente investiga las librerías y frameworks que podrían utilizarse para implementar la feature. Compara alternativas, documenta versiones compatibles y justifica la selección.

## Generación de archivos iCalendar

Se evaluaron tres opciones para generar archivos .ics:

- **icalendar** (v5.0): librería madura con soporte
  completo de RFC 5545. Mantenida activamente.
  Compatible con Python 3.10+.

- **ics.py** (v0.7): API más moderna pero menor
  cobertura del estándar. Sin soporte para VALARM.

- **vobject** (v0.9): abandonada desde 2021.
  No compatible con Python 3.12.

**Decisión**: usar icalendar v5.0 por cobertura
completa del estándar y mantenimiento activo.

Restricciones técnicas descubiertas: durante la investigación, el agente puede descubrir limitaciones o incompatibilidades que afectan al diseño. Estas se documentan en el research.md para que las fases posteriores las tengan en cuenta.

Patrones de referencia: si la feature requiere implementar patrones que ya existen en el ecosistema (autenticación OAuth, procesamiento de colas, generación de PDFs), el agente documenta las prácticas recomendadas y las adapta al contexto del proyecto.

El research.md funciona como un registro de decisiones (decision log). Cuando meses después alguien pregunta "por qué se eligió FastAPI en lugar de Flask", la respuesta está documentada con sus justificaciones.

data-model.md: el modelo de datos

El archivo data-model.md define las entidades, relaciones y estructuras de datos que la feature necesita. Este artefacto traduce los conceptos mencionados en las user stories de la especificación a estructuras técnicas concretas.

Un data-model.md típico incluye definiciones de entidades con sus atributos, tipos, restricciones y relaciones:

## Entidades

### CalendarEvent
| Campo       | Tipo        | Restricciones           |
|-------------|-------------|-------------------------|
| id          | UUID        | PK, auto-generado       |
| title       | String(200) | NOT NULL                |
| start_time  | DateTime    | NOT NULL, con timezone  |
| end_time    | DateTime    | NOT NULL, > start_time  |
| location    | String(200) | Nullable                |
| description | Text        | Nullable                |
| created_at  | DateTime    | NOT NULL, auto          |
| user_id     | UUID        | FK -> User              |

### EventShare
| Campo      | Tipo     | Restricciones            |
|------------|----------|--------------------------|
| id         | UUID     | PK, auto-generado        |
| event_id   | UUID     | FK -> CalendarEvent      |
| share_token| String   | UNIQUE, auto-generado    |
| expires_at | DateTime | Nullable                 |
| created_at | DateTime | NOT NULL, auto           |

Las relaciones entre entidades se documentan de forma explícita:

## Relaciones

- Un **User** tiene muchos **CalendarEvent** (1:N)
- Un **CalendarEvent** tiene muchos **EventShare** (1:N)
- Cada **EventShare** pertenece a un único
  **CalendarEvent**

erDiagram
    User ||--o{ CalendarEvent : "crea"
    CalendarEvent ||--o{ EventShare : "tiene"
    User {
        UUID id PK
        String email
        String name
    }
    CalendarEvent {
        UUID id PK
        String title
        DateTime start_time
        DateTime end_time
        String location
        UUID user_id FK
    }
    EventShare {
        UUID id PK
        UUID event_id FK
        String share_token
        DateTime expires_at
    }

El data-model.md no es un esquema de migración de base de datos. Es una representación lógica de los datos que la feature necesita. La traducción a un esquema físico (tablas SQL, documentos MongoDB, structs de código) ocurre durante la implementación.

El modelo de datos se construye directamente a partir de las user stories y criterios de aceptación del spec.md. Si una user story dice "el usuario puede añadir una ubicación opcional al evento", el modelo debe incluir un campo location con restricción Nullable. Esta trazabilidad entre requisitos y modelo de datos es una de las garantías de calidad que proporciona SDD.

contracts/: los contratos de API

El directorio contracts/ contiene las definiciones de interfaces que la feature expondrá o consumirá. En aplicaciones web, estos contratos suelen describir endpoints REST o GraphQL. En librerías, describen las funciones y clases públicas. En servicios de mensajería, describen los formatos de mensajes.

Un contrato de API REST típico incluye los endpoints, sus métodos HTTP, parámetros, cuerpos de request y response:

## POST /api/events

Crea un nuevo evento de calendario.

### Request Body

{
  "title": "Reunion de equipo",
  "start_time": "2026-03-15T10:00:00+01:00",
  "end_time": "2026-03-15T11:30:00+01:00",
  "location": "Sala A",
  "description": "Revisión semanal del sprint"
}

### Response 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Reunion de equipo",
  "start_time": "2026-03-15T10:00:00+01:00",
  "end_time": "2026-03-15T11:30:00+01:00",
  "location": "Sala A",
  "description": "Revisión semanal del sprint",
  "created_at": "2026-03-09T14:30:00+01:00",
  "download_url": "/api/events/550e.../download"
}

### Response 422 Validation Error

{
  "detail": [
    {
      "field": "end_time",
      "message": "end_time must be after start_time"
    }
  ]
}

Los contratos son especialmente valiosos en equipos donde el frontend y el backend se desarrollan en paralelo. Con los contratos definidos en Phase 1, el equipo de frontend puede empezar a trabajar con mocks basados en las respuestas documentadas, sin esperar a que el backend esté listo.

Contratos en formato OpenAPI

En proyectos que utilizan APIs REST, el agente puede generar contratos en formato OpenAPI (Swagger) dentro del directorio contracts/. Estos archivos .json o .yaml siguen el estándar OpenAPI 3.x y pueden importarse directamente en herramientas como Swagger UI, Postman o Insomnia para documentación y testing interactivo.

quickstart.md: la guía de arranque rápido

El archivo quickstart.md es una guía de referencia rápida que condensa las instrucciones necesarias para que un desarrollador arranque la feature desde cero. No es un tutorial detallado, sino una lista concisa de pasos que cubre:

• Dependencias a instalar: qué paquetes añadir al proyecto y con qué versiones.
• Variables de entorno: qué configuración necesita la feature para funcionar.
• Comandos de setup: cómo inicializar la base de datos, ejecutar migraciones o configurar servicios externos.
• Verificación: cómo comprobar que el setup funciona correctamente.

## Quick Start

### 1. Instalar dependencias

pip install icalendar==5.0.13 fastapi sqlalchemy

### 2. Variables de entorno

DATABASE_URL=postgresql://localhost:5432/calendar
SECRET_KEY=cambiar-en-produccion

### 3. Ejecutar migraciones

alembic upgrade head

### 4. Verificar

pytest tests/ -v

El quickstart.md reduce la fricción de onboarding. Un desarrollador nuevo en la feature puede leerlo en dos minutos y tener el entorno preparado para empezar a trabajar.

Este artefacto es consumido por el agente IA durante la fase de implementación (/speckit.implement), donde lo utiliza como referencia para configurar el entorno antes de generar código.

Relación entre artefactos

Los cinco artefactos de planificación no son documentos aislados. Forman una red de información donde cada uno complementa a los demás:

flowchart TB
    SPEC["spec.md<br>Requisitos"] --> RESEARCH["research.md<br>Investigación"]
    RESEARCH --> PLAN["plan.md<br>Decisiones técnicas"]
    SPEC --> DATAMODEL["data-model.md<br>Modelo de datos"]
    PLAN --> CONTRACTS["contracts/<br>Interfaces"]
    PLAN --> QS["quickstart.md<br>Arranque rápido"]
    DATAMODEL --> CONTRACTS
    PLAN --> TASKS["tasks.md<br>Fase siguiente"]
    CONTRACTS --> TASKS
    DATAMODEL --> TASKS

• El research.md informa las decisiones del plan.md (las librerías investigadas determinan las dependencias del plan).
• El data-model.md alimenta los contracts/ (las entidades del modelo se reflejan en los cuerpos de request/response de la API).
• El plan.md y los contracts/ alimentan las tareas (tasks.md) que se generarán en la fase siguiente.
• El quickstart.md sintetiza la información del plan.md en pasos accionables.

Esta estructura modular permite que cada artefacto se revise, valide y actualice de forma independiente. Si el equipo decide cambiar la base de datos de PostgreSQL a SQLite, solo necesita actualizar el plan.md, el data-model.md y el quickstart.md. La especificación y los contratos de API permanecen sin cambios, porque el almacenamiento es un detalle de implementación que no afecta a la interfaz pública del sistema.

Artefactos en proyectos brownfield

En proyectos con código existente, los artefactos de planificación adquieren un matiz diferente. El research.md no solo investiga librerías nuevas, sino que documenta cómo se integran con las dependencias existentes. El data-model.md describe las entidades nuevas y su relación con las tablas o colecciones que ya están en producción.

El plan.md en un contexto brownfield presta especial atención a la estructura de directorios existente, adaptando la organización propuesta para que sea coherente con lo que ya hay en el repositorio. En lugar de proponer una estructura desde cero, el plan documenta dónde se ubicarán los nuevos archivos dentro de la estructura actual.

Los contratos en contracts/ también reflejan esta integración: si la API existente ya tiene un formato de respuesta establecido (paginación, manejo de errores, formato de fechas), los contratos de la nueva feature siguen las mismas convenciones para mantener la coherencia.