SpecFlow: Cursor에서의 멀티 에이전트 SDD (4단계, /approve, 단일 코드 작성자)

SpecFlow는 당신의 저장소(Repository)에 **Spec-Driven Development (SDD, 명세 주도 개발)**를 설치하는 CLI입니다. 단계별로 4개의 에이전트가 작동하며, 명세(Specs)는 마크다운(Markdown) 형식으로 작성되고, 오직 Implementer만이 소스 코드를 편집할 수 있습니다. Cursor 내에서 채팅 방식으로 작동하며, 기능(Feature) 구현이 필요할 때 흐름(Flow)을 활성화합니다.

@ceatoleii/specflow · 파이프라인(Pipeline): 요구사항(Requirement) → 계획(Plan) → 작업(Tasks) → 코드(Code) → 검토(Review)

npx @ceatoleii/specflow init

전체 가이드: ceatoleii.github.io/specflow/es

해결하는 문제

증상	SpecFlow 메커니즘
모호한 요구사항 → 거대한 diff	Refiner → AC1, AC2...가 포함된 task.md
...
파이프라인(Pipeline): 요구사항(Requirement) → 계획(Plan) → 작업(Tasks) → 코드(Code) → 검토(Review)

flowchart LR
  R[Refining<br/>task.md] --> D[Designing<br/>plan.md + tasks.md]
  D -->|/approve| I[Implementing<br/>src/]
...

60초 아키텍처

단계 (phase.md)	에이전트	코드 작성 여부?	출력물
refining	Refiner	아니오	task.md
...

직접 모드 vs 흐름(Flow) 모드

	직접 모드	흐름 모드
신호	.agents-state/.flow-enabled 없음	파일 존재
...

설치 (2분)

요구사항: Node.js ≥ 18, 대화형 터미널(Interactive terminal), 프로젝트 루트(Root).

npx @ceatoleii/specflow init
specflow doctor

.gitignore에 추가:

.agents-state/

init이 설치하는 항목

경로	관리 주체	비고
AGENTS.md	SpecFlow (init / sync)	모든 IDE를 위한 입력값
...

황금률: 본격적인 작업을 시작하기 전에 .agents-docs/를 완성하세요. 에이전트들은 매 흐름마다 이를 읽습니다.

워크스루(Walkthrough): /api/search의 속도 제한(Rate limiting)

예시 기능(Feature):

IP당 분당 최대 100회 요청, 표준 JSON을 사용하는 HTTP 429, 기존 테스트는 통과(Green) 상태.

1. 흐름 활성화

Cursor 채팅에서:

nueva tarea

대안: flow on, activar flujo, 또는 nueva tarea desde LIN-123 (Linear + MCP).

확인 사항:

specflow doctor
# .flow-enabled 및 phase.md = refining 상태가 보여야 함

2. Refining → task.md

Refiner(정제기)가 질문하면 사용자가 응답합니다. 전형적인 결과물:

# Task: Rate limit /api/search

## Goal
...

사용자는 ACs (Acceptance Criteria, 수락 기준) 및 Out of Scope (범위 외 사항)를 검토합니다. 파일을 직접 편집할 필요는 없으며, 잘못된 부분이 있다면 채팅에서 수정하십시오.

3. Designing → plan.md + tasks.md

SDD (Software Design Document)가 설계를 제안합니다. tasks.md의 일부 (TDD 순서):

## Tasks

- [ ] [test] 통합 테스트 추가: 60초 내 101개 요청 → 429 (AC1)
...

plan.md (파일, 접근 방식)를 읽으십시오. 만약 계획에 요청하지 않은 리팩토링 (Refactor)이 포함되어 있다면, 승인하기 전에 변경을 요청하십시오.

4. /approve 게이트

/approve

aprobado, dale 도 유효합니다.

• 단계(Phase) → implementing (구현 중)
• 이제서야 Implementer (구현자)가 src/ 디렉토리를 수정할 수 있습니다.
• Linear가 활성화된 경우: 이슈(Issue) → In Progress (Cursor 내 MCP를 통해)

5. Implementing

다음 사항을 모니터링하십시오:

• tasks.md — [ ] → [~] → `[x]
• git diff — plan.md와 일치해야 함

사양(Spec)에 모호함이 있다면 채팅으로 응답하십시오. Implementer는 추측해서는 안 됩니다.

6. Reviewing → review.md

Reviewer (검토자)는 .agents-docs/verification.md에 정의된 명령(예: npm test, npm run lint)을 실행합니다.

review.md 예시:

# Review: Rate limit /api/search

## Acceptance Criteria
...

결과	조치 사항
PASS	history/YYYY-MM-DD-slug/ 생성, 흐름(Flow) 종료
FAIL	구체적인 목록과 함께 Implementer에게 반환

5가지 설계 원칙

1. 코드보다 사양(Spec) 우선 — /approve 없이는 구현도 없습니다.
2. 단일 작성자 (Single Writer) — src/, lib/ 등은 오직 Implementer만 수정합니다.
3. 명시적 상태 (Explicit State) — .agents-state/current/ 내의 phase.md, task.md, plan.md를 통해 관리합니다.
4. 이식 가능한 규칙 (Portable Rules) — sync를 포함한 .agents/ 폴더; 프로젝트의 사실 관계는 .agents-docs/에 저장합니다 (sync에 의해 절대 덮어쓰이지 않음).
5. 기본적으로 오버헤드 제로 — 활성화된 작업이 없으면 어시스턴트는 일반 상태로 동작합니다.

일상적인 명령어

명령어	시점
specflow init	최초 설치 시
...

specflow status
specflow sync

Linear + Cursor MCP (선택 사항)

• 설정: specflow linear setup 또는 init 시 위저드(wizard) 사용
• CLI에서 API 키를 사용하지 않음 — Cursor의 에이전트가 Linear MCP 플러그인을 호출합니다.
• 기본 이벤트:

SpecFlow 이벤트	Linear 상태
Refining 완료	Todo
...
상세 정보: Linear 통합 (Linear Integration)

SpecFlow를 사용하지 말아야 할 때

흐름(flow) 사용	건너뛰기 (직접 모드)
AC(수락 기준) 및 범위가 있는 기능(Feature)	한 줄 수정
...

팀 협업

커밋할 항목: AGENTS.md, .agents/, .agents-docs/, 어댑터(adapters), .specflow-version

커밋하지 말 것: .agents-state/

npx @ceatoleii/specflow sync   # 엔진 업데이트; .agents-docs/ 보존

빠른 문제 해결 (Troubleshooting)

문제	첫 번째 단계
어시스턴트가 단계를 무시함	.flow-enabled 파일이 존재하는가? specflow doctor 실행
...
더 보기: 문제 해결 (Troubleshooting)

요약

• npx @ceatoleii/specflow init으로 규칙과 템플릿을 설치합니다.
• 계약(contract)이 중요할 때 새 작업(nueva tarea)으로 활성화합니다.
• Diff(차이)를 생성하기 전 /approve로 설계를 승인합니다.
• 단일 에이전트가 코드를 작성하고, **Reviewer(검토자)**가 AC에 따른 증거와 함께 마무리합니다.

링크

• npm: @ceatoleii/specflow
• Repo: github.com/ceatoleii/specflow
• Docs ES: ceatoleii.github.io/specflow/es
• SDD 관련 추가 컨텍스트: 리포지토리 내 article-medium-es.md

/approve로 어떤 기능을 가장 먼저 테스트해보고 싶으신가요? 👇