SpecFlow: desarrollo spec-driven (SDD) con 4 agentes de IA en Cursor

Un CLI open source que instala en tu repo un flujo Requisito → Plan → Código → Revisión: specs en markdown, /approve antes del diff y un solo agente que puede editar src/.

En una frase

SpecFlow ([@ceatoleii/specflow](https://www.npmjs.com/package/@ceatoleii/specflow)) no sustituye Cursor: le añade Spec-Driven Development (SDD) con cuatro agentes especializados que trabajan por fases y dejan el contrato en archivos del repositorio — no solo en el historial del chat.

npx @ceatoleii/specflow init

Si ya usas IA para codear, el siguiente salto no es “un prompt más largo”. Es separar requisito, diseño, implementación y revisión — y decidir cuándo se permite tocar el código.

Capa 1 — Qué falla en el chat sin estructura

Cursor (y herramientas similares) responden bien a preguntas concretas. El problema aparece en tareas con alcance: el modelo mezcla plan y patch, amplía el scope y declara “listo” sin criterios verificables.

Lo que pasaConsecuenciaPides una feature en una líneaDiff grande, archivos no pedidosEl plan vive solo en el chatNueva sesión = reglas desde ceroVarios “roles” en un hiloNadie es dueño único del códigoSin ACs escritosEl lunes no hay evidencia de “hecho”

Eso no es un fallo de Cursor. Es chat sin contrato persistente. SDD pone el contrato antes del primer cambio en src/.

Capa 2 — Qué es SDD aquí (y qué aporta SpecFlow)

Spec-Driven Development significa: acordar requisito y diseño en artefactos legibles, implementar solo lo aprobado, cerrar con revisión contra criterios — no contra la intuición del modelo.

SpecFlow instala ese ciclo en el repo:

PiezaDónde vivePara quéReglas de agentes.agents/ (CLI)Refiner, SDD, Implementer, ReviewerConocimiento de tu proyecto.agents-docs/ (tú)Stack, convenciones, verification.mdEstado de la tarea activa.agents-state/current/ (runtime)task.md, plan.md, phase.md…Entrada en Cursor.cursor/rules/_specflow.mdcEl asistente enruta por fase

No es un framework de app. Es orquestación spec-driven dentro del flujo que ya usas.

Capa 3 — Los cuatro agentes (y por qué solo uno escribe código)

Cada mensaje en modo flujo pasa por un orquestador que lee phase.md y activa un rol:

AgenteFaseSalida¿Edita código fuente?Refinerrefiningtask.md (AC1, AC2…)NoSDDdesigningplan.md, tasks.mdNoImplementerimplementingCódigo + checklistSí — únicoReviewerreviewingreview.mdNo

Pipeline: Requisito → Plan → Tareas → Código → Revisión

Activas el flujo con nueva tarea, flow on o activar flujo. Lo apagas con flow off / modo directo.

Sin tarea activa (modo directo), Cursor se comporta como siempre — cero overhead hasta que tú eliges SDD para esa feature.

Capa 4 — La puerta /approve (spec antes que código)

El SDD presenta plan.md y tasks.md y espera tu autorización explícita:

/approve

Hasta entonces ningún agente puede modificar src/, lib/, etc. Separar “acepto el diseño” de “genera el diff” es el núcleo del SDD en SpecFlow: evita implementación adelantada y scope creep en el mismo hilo.

Con Linear (opcional, MCP en Cursor): nueva tarea desde LIN-123 y sync de estados al aprobar y al PASS en revisión.

Capa 5 — Cómo se ve en la práctica (ejemplo: rate limiting)

Feature acotada para seguir el hilo sin ficción:

Rate limit en GET /api/search: 100 req/min por IP, 429 + JSON estándar, tests actuales en verde.

Paso 1 — Refining. Refiner pregunta (ventana fija vs sliding, forma del JSON, tests existentes) y escribe task.md:

## Acceptance Criteria
- **AC1:** >100 req/min misma IP → HTTP 429
- **AC2:** Body `{ "error": "rate_limit_exceeded", "retryAfter": <n> }`
- **AC3:** Tests de search sin regresiones
## Out of Scope
- Cuotas por API key, dashboard de métricas

Paso 2 — Designing. SDD propone archivos y tasks.md con [test] antes de [impl]. Tú lees; si el plan mete refactors extra, corriges en chat antes de /approve.

Paso 3 — Implementing. Solo Implementer toca código; tasks.md marca progreso; git diff alinea con plan.md.

Paso 4 — Reviewing. Reviewer ejecuta .agents-docs/verification.md, documenta evidencia por AC en review.md. PASS → archivo en history/YYYY-MM-DD-slug/, flujo off.

En cada paso añades información al repo; el lector (o tú el lunes) no depende de exportar el chat.

Capa 6 — Modo directo vs modo flujo

Modo directoModo flujoDefaultSíSolo si lo activasIdeal paraTypos, spikes, exploraciónFeatures con ACs y alcanceArtefactosNinguno obligatoriocurrent/ con specs

La idea no es “ser ceremonioso siempre”. Es tener SDD multi-agente en Cursor cuando el coste de un mal diff supera dos minutos de nueva tarea.

Capa 7 — Equipo, sync y límites

• Commitear: AGENTS.md, .agents/, .agents-docs/, adaptadores.
• No commitear: .agents-state/ (sesión por dev).
• Actualizar motor: specflow sync — no pisa .agents-docs/.
• Verificar: specflow doctor y specflow doctor --run.

No es: framework web, agente en la nube, ni reemplazo de Cursor. Es: SDD + 4 roles + estado en markdown, empaquetado para tu repo.

Cierre — Tres ideas que encadenan todo lo anterior

1. SDD = contrato en disco antes del código.
2. Multi-agente = un rol por fase, un solo escritor de src/.
3. Cursor = misma UI de chat; el repo (task.md, plan.md, review.md) es la memoria.

npx @ceatoleii/specflow init
specflow doctor

Documentación: ceatoleii.github.io/specflow/es · GitHub

MIT · @ceatoleii/specflow