DEV Community

Cover image for SpecFlow: SDD multi-agente en Cursor (4 fases, /approve, un solo escritor de código)
Matías Espinoza
Matías Espinoza

Posted on • Originally published at ceatoleii.github.io

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

#cursor #ai #opensource #devtools

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
Enter fullscreen mode Exit fullscreen mode

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

Qué problema resuelve

Síntoma Mecanismo SpecFlow
Requisito vago → diff enorme Refiner → task.md con AC1, AC2…
Código antes de acordar diseño SDD espera /approve
Varios “agentes” tocando src/ Solo Implementer escribe fuente
“Listo” sin evidencia Reviewer → review.md por AC

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
Enter fullscreen mode Exit fullscreen mode

Arquitectura en 60 segundos

Fase (phase.md) Agente ¿Escribe código? Salida
refining Refiner No task.md
designing SDD No plan.md, tasks.md
implementing Implementer Sí Código + tasks.md
reviewing Reviewer No review.md

Modo directo vs modo flujo

Modo directo Modo flujo
Señal Sin .agents-state/.flow-enabled Archivo presente
Activar — nueva tarea, flow on, activar flujo
Apagar — flow off, modo directo
Uso Typos, spikes, exploración Features con ACs claros

Instalación (2 minutos)

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

npx @ceatoleii/specflow init
specflow doctor
Enter fullscreen mode Exit fullscreen mode

Añade al .gitignore:

.agents-state/
Enter fullscreen mode Exit fullscreen mode

Qué instala init

Ruta Quién la mantiene Notas
AGENTS.md SpecFlow (init / sync) Entrada para cualquier IDE
.agents/ SpecFlow Reglas de fase — no editar
.agents-docs/ Tú Stack, convenciones, verification.md
.agents-state/ Runtime Estado por tarea — gitignore
.cursor/rules/_specflow.mdc SpecFlow Adaptador Cursor (default v2.2+)
.specflow-linear.json Opcional Sync Linear vía MCP en Cursor

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
Enter fullscreen mode Exit fullscreen mode

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

Comprueba:

specflow doctor
# Debe ver .flow-enabled y phase.md = refining
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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

4. Puerta /approve 

/approve
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode
Resultado Qué pasa
PASS history/YYYY-MM-DD-slug/, flujo apagado
FAIL Vuelve a Implementer con lista concreta

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

Comando Cuándo
specflow init Primera instalación
specflow doctor Verificar archivos y fase
specflow doctor --run + ejecutar verification.md
specflow status Versión, Linear on/off, updates
specflow sync Actualizar motor y adaptadores
specflow linear setup Habilitar sync Linear (MCP) 
specflow status
specflow sync
Enter fullscreen mode Exit fullscreen mode

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:
Evento SpecFlow Estado Linear
Refining completo Todo
/approve In Progress
Review PASS Done

Detalle: Integración Linear

Cuándo NO usar SpecFlow

Usa flujo Omite (modo directo)
Feature con ACs y alcance Fix de una línea
Quieres leer plan antes del diff Spec ya firmada fuera del repo
Equipo con mismas reglas en .agents/ Spike exploratorio 100% ad-hoc

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/
Enter fullscreen mode Exit fullscreen mode

Troubleshooting rápido

Problema Primer paso
El asistente ignora fases ¿Existe .flow-enabled? specflow doctor
Código sin plan ¿Dijiste /approve? Revisa phase.md
Review falla tests Completa .agents-docs/verification.md

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

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

Top comments (0)