El comando /speckit.plan

De la especificación al plan técnico

Tras definir qué construir con /speckit.specify y resolver ambigüedades con /speckit.clarify, llega el momento de decidir cómo construirlo. Este es el propósito del comando /speckit.plan: transformar una especificación de negocio en un plan de implementación técnica que el agente IA seguirá durante la fase de construcción.

La separación entre especificación y planificación es una decisión arquitectónica deliberada de SDD. La especificación describe requisitos y valor de negocio sin mencionar tecnologías. El plan, en cambio, toma esos requisitos y determina el stack tecnológico, la estructura del proyecto, los contratos de API, el modelo de datos y las decisiones de arquitectura necesarias para satisfacerlos.

La especificación responde a "qué" y "por qué". El plan responde a "cómo", "con qué" y "dónde". Mezclar ambas preguntas en un solo documento produce decisiones técnicas sesgadas por la prisa.

Esta separación tiene un beneficio práctico inmediato. Si en el futuro se decide cambiar el stack tecnológico (por ejemplo, migrar de Express a FastAPI), la especificación permanece intacta. Solo se regenera el plan con las nuevas decisiones técnicas, y el resto del flujo SDD se adapta automáticamente.

Cómo ejecutar el comando

El comando /speckit.plan se ejecuta dentro del chat del agente IA, sin argumentos adicionales. El agente detecta automáticamente la feature activa a partir de la rama Git o de la variable de entorno SPECIFY_FEATURE:

/speckit.plan

Al recibir el comando, el agente ejecuta una secuencia de operaciones coordinadas:

• 1. Lee el spec.md de la feature activa desde el directorio specs/{numero-feature}/. Si no existe un archivo de especificación, el comando se detiene con un error indicando que primero debe ejecutarse /speckit.specify.

• 2. Lee la constitución del proyecto desde .specify/memory/constitution.md. Los principios definidos en la constitución actúan como restricciones que el plan debe respetar.

• 3. Realiza preguntas de contexto técnico al usuario cuando ciertos aspectos no pueden inferirse del spec.md ni de la constitución. Estas preguntas cubren decisiones como el framework CSS, las librerías de UI, el framework de testing o los servicios externos que se van a utilizar.

• 4. Ejecuta la investigación técnica (Phase 0), donde el agente analiza la documentación relevante, las dependencias del proyecto y las mejores prácticas para el stack que se va a emplear.

• 5. Genera los artefactos de planificación (Phase 1): el archivo plan.md, el research.md, el data-model.md, los contratos en contracts/ y el quickstart.md.

• 6. Verifica la conformidad del plan generado con la constitución del proyecto, asegurando que ninguna decisión técnica viola los principios establecidos.

flowchart LR
    SPEC["spec.md"] --> CMD["/speckit.plan"]
    CONST["constitution.md"] --> CMD
    CMD --> PLAN["plan.md"]
    CMD --> RESEARCH["research.md"]
    CMD --> DATA["data-model.md"]
    CMD --> CONTRACTS["contracts/"]
    CMD --> QS["quickstart.md"]

Preguntas de contexto técnico

A diferencia de /speckit.specify, que recibe un prompt descriptivo, /speckit.plan es un comando interactivo que puede formular preguntas antes de generar el plan. Estas preguntas aparecen cuando el agente necesita información técnica que no puede deducir de los artefactos existentes.

Antes de generar el plan necesito aclarar
algunos aspectos técnicos:

1. ¿Qué framework CSS o sistema de estilos
   prefieres? (ej: Tailwind, CSS Modules, Sass)

2. ¿Utilizarás algún servicio externo de
   autenticación? (ej: Auth0, Supabase Auth, propio)

3. ¿Cuál es el framework de testing preferido?
   (ej: pytest, Jest, Vitest)

Estas preguntas son técnicas, no funcionales. No cambian lo que el sistema hace (eso ya está definido en el spec.md), sino las herramientas y librerías con las que se construirá. El usuario responde y el agente incorpora las decisiones al plan.

Si el usuario no tiene preferencia sobre algún aspecto, puede indicar al agente que elija la opción más adecuada. El agente seleccionará basándose en la constitución del proyecto y en las prácticas del ecosistema.

El archivo plan.md generado

El artefacto principal del comando es el archivo plan.md, un documento estructurado que sirve como referencia técnica central para las fases de tareas e implementación.

El plan.md se organiza en secciones estandarizadas que el agente IA genera a partir de la plantilla plan-template.md del proyecto:

Cabecera y contexto

La primera parte del plan contiene metadatos que vinculan el plan con la feature y la especificación:

# Implementation Plan: Crear eventos de calendario

**Branch**: `001-crear-eventos-calendario`
**Date**: 2026-03-09
**Spec**: specs/001-crear-eventos-calendario/spec.md

Contexto técnico

La sección de contexto técnico documenta las decisiones de stack que guiarán toda la implementación. Cada campo captura un aspecto concreto del entorno técnico:

## Technical Context

**Language/Version**: Python 3.12
**Primary Dependencies**: FastAPI, SQLAlchemy, Alembic
**Storage**: PostgreSQL 16
**Testing**: pytest + httpx
**Target Platform**: Linux server (Docker)
**Project Type**: web-service
**Performance Goals**: 500 req/s, respuesta < 200ms p95
**Constraints**: < 512MB memoria, compatible con ARM64
**Scale/Scope**: 10k usuarios, 100k eventos

Cada campo que el agente no puede determinar a partir de la especificación o la constitución se marca con NEEDS CLARIFICATION, lo que fuerza la resolución antes de continuar.

Resumen técnico

Tras el contexto, el plan incluye un resumen que conecta los requisitos de la especificación con la solución técnica propuesta:

## Summary

La feature requiere un servicio de creación y
exportación de eventos de calendario en formato
iCalendar (RFC 5545). Se implementará como un
endpoint REST en FastAPI con validación de datos
mediante Pydantic y generación de archivos .ics
mediante la librería icalendar.

Este resumen es el puente narrativo entre el "qué" (spec.md) y el "cómo" (el resto del plan). Debe ser lo suficientemente concreto para que cualquier desarrollador entienda la estrategia técnica sin leer el documento completo.

Estructura del proyecto en el plan

El plan.md incluye una sección que define la organización del código fuente que se generará durante la implementación. Spec Kit proporciona varias estructuras predefinidas que el agente selecciona según el tipo de proyecto:

Proyecto único (librería, CLI, servicio):

src/
├── models/
├── services/
├── cli/
└── lib/

tests/
├── contract/
├── integration/
└── unit/

Aplicación web (frontend + backend):

backend/
├── src/
│   ├── models/
│   ├── services/
│   └── api/
└── tests/

frontend/
├── src/
│   ├── components/
│   ├── pages/
│   └── services/
└── tests/

El agente selecciona la estructura que mejor se ajusta a la constitución y al tipo de proyecto detectado en el contexto técnico. Esta estructura aparece documentada en el plan para que todo el equipo tenga visibilidad sobre dónde se ubicará cada componente.

Iterar sobre el plan

Al igual que la especificación, el plan no tiene por qué ser definitivo en su primera versión. El flujo SDD permite iterar sobre el plan de varias formas:

Ejecutar /speckit.plan de nuevo con más contexto: si tras revisar el plan el equipo decide que ciertas decisiones técnicas deben cambiar, se puede volver a ejecutar el comando. El agente regenerará el plan incorporando el nuevo feedback.

/speckit.plan

Cambiar el storage de PostgreSQL a SQLite
para simplificar el despliegue en la fase
inicial. Mantener el resto de decisiones.

Editar plan.md manualmente: dado que el plan es un archivo Markdown estándar, el equipo puede modificar directamente las secciones que necesiten ajustes. Esto es útil para decisiones que el equipo quiere tomar sin pasar por el agente.

Volver a la fase de especificación: si durante la planificación se descubre que la especificación es incompleta o ambigua, se puede volver a ejecutar /speckit.specify o /speckit.clarify para refinar el spec.md antes de regenerar el plan.

flowchart TB
    SPEC["spec.md"] --> PLAN1["/speckit.plan<br>Plan v1"]
    PLAN1 --> REVIEW["Revisión del equipo"]
    REVIEW -->|Cambiar stack| PLAN2["/speckit.plan<br>con nuevo contexto"]
    REVIEW -->|Ajustes menores| EDIT["Edición manual<br>del plan.md"]
    REVIEW -->|Spec incompleta| BACK["Volver a<br>/speckit.specify"]
    PLAN2 --> TASKS["/speckit.tasks"]
    EDIT --> TASKS
    BACK --> SPEC

La iteración en la fase de planificación tiene un coste bajo comparado con la iteración durante la implementación. Cambiar una decisión en el plan.md lleva minutos. Cambiar esa misma decisión cuando ya hay código generado puede requerir refactorizar múltiples archivos.

Archivos de contexto y proyectos brownfield

En proyectos donde ya existe código (brownfield), el comando /speckit.plan genera mejores resultados cuando recibe archivos de contexto que muestran la estructura actual del proyecto:

/speckit.plan

@src/models/user.py @src/api/routes.py @pyproject.toml

Al incluir archivos existentes como referencia, el agente adapta el plan a la realidad del proyecto. En lugar de proponer una estructura nueva desde cero, el plan se integra con los modelos, rutas y dependencias que ya existen. Esto evita que la implementación posterior genere código que duplique o contradiga lo que ya está en el repositorio.

En proyectos greenfield (sin código previo), el contexto viene exclusivamente de la especificación y la constitución, por lo que el agente tiene libertad total para proponer la arquitectura más adecuada.