SpecFlow: SDD multi-agente en Cursor (4 fases, /approve, un solo escritor de código)

SpecFlow es un CLI que instala Spec-Driven Development (SDD) en tu repositorio: cuatro agentes por fase, specs en markdown y solo Implementer puede editar código fuente. Sigue siendo chat en Cursor — activas el flujo cuando la feature lo merece.

@ceatoleii/specflow · Pipeline: Requisito → Plan → Tareas → Código → Revisión

npx @ceatoleii/specflow init

Guía completa: ceatoleii.github.io/specflow/es

Qué problema resuelve

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

flowchart LR
  R[Refining<br/>task.md] --> D[Designing<br/>plan.md + tasks.md]
  D -->|/approve| I[Implementing<br/>src/]
  I --> V[Reviewing<br/>review.md]
  V -->|PASS| A[history/ + flow off]
  V -->|FAIL| I

Arquitectura en 60 segundos

Modo directo vs modo flujo

Instalación (2 minutos)

Requisitos: Node.js ≥ 18, terminal interactiva, raíz del proyecto.

npx @ceatoleii/specflow init
specflow doctor

Añade al .gitignore:

.agents-state/

Qué instala init

Regla de oro: completa .agents-docs/ antes de tareas serias — los agentes leen eso en cada flujo.

Walkthrough: rate limiting en /api/search

Feature de ejemplo:

Máx. 100 req/min por IP, HTTP 429 con JSON estándar, tests existentes en verde.

1. Activar flujo

En el chat de Cursor:

nueva tarea

Alternativas: flow on, activar flujo, o nueva tarea desde LIN-123 (Linear + MCP).

Comprueba:

specflow doctor
# Debe ver .flow-enabled y phase.md = refining

2. Refining → task.md

El Refiner pregunta; tú respondes. Resultado típico:

# Task: Rate limit /api/search

## Goal
Limit anonymous traffic to /api/search without breaking current behavior.

## Acceptance Criteria

- **AC1:** >100 requests/min from same IP → HTTP 429
- **AC2:** Body `{ "error": "rate_limit_exceeded", "retryAfter": <number> }`
- **AC3:** Existing search endpoint tests pass unchanged

## Constraints

- Reuse existing error middleware patterns if present
- No new env vars without team approval

## Out of Scope

- Per-API-key quotas
- Admin dashboard for limits

Tú revisas ACs y Out of Scope — no hace falta editar el archivo; corrige en chat si algo falla.

3. Designing → plan.md + tasks.md

El SDD propone diseño. Fragmento de tasks.md (orden TDD):

## Tasks

- [ ] [test] Add integration test: 101 requests in 60s → 429 (AC1)
- [ ] [test] Assert JSON body shape matches AC2
- [ ] [impl] Create rateLimit middleware (in-memory store, 100/min)
- [ ] [impl] Wire middleware on /api/search route only
- [ ] [impl] Run full search test suite (AC3)

Lee plan.md (archivos, enfoque). Si el plan incluye refactors no pedidos, pide cambios antes de aprobar.

4. Puerta /approve

/approve

También válido: aprobado, dale.

• Fase → implementing
• Solo ahora Implementer puede tocar src/
• Con Linear habilitado: issue → In Progress (vía MCP en Cursor)

5. Implementing

Monitorea:

• tasks.md — [ ] → [~] → [x]
• git diff — debe alinearse con plan.md

Si hay ambigüedad en la spec, responde en chat; el Implementer no debe adivinar.

6. Reviewing → review.md

El Reviewer ejecuta comandos de .agents-docs/verification.md (ej. npm test, npm run lint).

Ejemplo review.md:

# Review: Rate limit /api/search

## Acceptance Criteria

| AC | Evidence | Status |
|----|----------|--------|
| AC1 | `rate-limit.test.ts` — 101 req → 429 | PASS |
| AC2 | Snapshot `error` + `retryAfter` fields | PASS |
| AC3 | `npm test -- search` — 0 failures | PASS |

## Verification

- `npm test` — exit 0
- `npm run lint` — exit 0

## Decision

**PASS** — archived to history/, flow disabled.

Los 5 principios de diseño

1. Spec antes que código — Sin /approve, no hay implementación.
2. Un solo escritor — Solo Implementer en src/, lib/, etc.
3. Estado explícito — phase.md, task.md, plan.md en .agents-state/current/.
4. Reglas portables — .agents/ con sync; hechos del proyecto en .agents-docs/ (nunca sobrescrito por sync).
5. Cero overhead por defecto — Sin tarea activa, el asistente es normal.

Comandos del día a día

specflow status
specflow sync

Linear + Cursor MCP (opcional)

• Config: specflow linear setup o wizard en init
• No usa API keys en el CLI — el agente en Cursor llama al plugin Linear MCP
• Eventos por defecto:

Detalle: Integración Linear

Cuándo NO usar SpecFlow

Trabajo en equipo

Commitear: AGENTS.md, .agents/, .agents-docs/, adaptadores, .specflow-version

No commitear: .agents-state/

npx @ceatoleii/specflow sync   # actualiza motor; preserva .agents-docs/

Troubleshooting rápido

Más: Solución de problemas

Resumen

• Instalas reglas y plantillas con npx @ceatoleii/specflow init
• Activas con nueva tarea cuando el contrato importa
• Apruebas diseño con /approve antes del diff
• Un agente escribe código; Reviewer cierra con evidencia por AC

Links

• npm: @ceatoleii/specflow
• Repo: github.com/ceatoleii/specflow
• Docs ES: ceatoleii.github.io/specflow/es
• Más contexto SDD: article-medium-es.md en el repo

¿Qué feature probarías primero con /approve? 👇