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

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



Tópico: SpecFlow: SDD multi-agente en Cursor (4 fases, /approve, un solo escritor de código)
Categoria: Tutoriais | Programação & Tecnologia
Idioma Principal: Português (Conteúdo de Tecnologia)

Descrição do Conteúdo / Informações:
-------------------------------------------------------------------------


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


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
task.md] --> D[Designing
plan.md + tasks.md]
D -->|/approve| I[Implementing
src/]
I --> V[Reviewing
review.md]
V -->|PASS| A[history/ + flow off]
V -->|FAIL| I



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

Añade al .gitignore:

.agents-state/



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

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 — [ ] → [~] →

•
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.

Resultado
Qué pasa

PASS

history/YYYY-MM-DD-slug/, flujo apagado

FAIL
Vuelve a Implementer con lista concreta



Los 5 principios de diseño


•
Spec antes que código — Sin /approve, no hay implementación.

•
Un solo escritor — Solo Implementer en src/, lib/, etc.

•
Estado explícito — phase.md, task.md, plan.md en .agents-state/current/.

•
Reglas portables — .agents/ con sync; hechos del proyecto en .agents-docs/ (nunca sobrescrito por sync).

•
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



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/



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

• 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? 👇