marcusgoll/Spec-Flow

Spec-Flow는 Claude Code를 위한 워크플로 툴킷 (workflow toolkit)으로, AI를 활용한 소프트웨어 구축 방식을 변화시킵니다. 임시방편적인 프롬프팅 (ad-hoc prompting) 대신, 아이디어를 명세 (specification) 단계부터 프로덕션 (production) 단계까지 전달하는 구조화된 파이프라인 (pipeline)을 제공합니다.

/feature "add user authentication"

이것이 전부입니다. Spec-Flow가 나머지 과정을 처리합니다: 명세 작성, 아키텍처 (architecture) 계획, 작업 분할, 테스트 주도 개발 (TDD) 기반 구현, 품질 게이트 (quality gates) 실행, 그리고 배포 (deploying)까지 말이죠.

Spec-Flow 미사용 시	Spec-Flow 사용 시
"우리가 무엇을 만들고 있었죠?"	모든 결정 사항이 NOTES.md에 기록됨
...	...

npx spec-flow init

이 명령은 워크플로 파일들을 프로젝트에 직접 복사합니다 (.claude/, .spec-flow/, CLAUDE.md). package.json에 어떠한 의존성 (dependency)도 추가되지 않으며, Spec-Flow는 여러분의 코드베이스 (codebase)의 일부가 됩니다.

npx spec-flow ...는 설치 및 유지보수를 위한 CLI (Command Line Interface)입니다. 설치 후에는 도구 환경 내부에서 /feature, /plan, /ship과 같은 설치된 워크플로 명령어를 사용합니다.

/feature "add dark mode toggle"

Spec-Flow는 다음 과정을 안내합니다:

spec → plan → tasks → implement → optimize → ship

각 단계는 산출물 (artifacts)을 생성하고, 품질 검사 (quality checks)를 실행하며, 다음 단계로 깔끔하게 인계됩니다.

기능 구현이 배포되었습니다. 모든 결정 사항이 문서화되었습니다. 테스트는 통과했습니다. 다음 작업을 시작할 준비가 되었습니다.

언제든 업데이트를 확인하세요:

npx spec-flow status

최신 버전으로 업데이트하세요:

npx spec-flow update

CI/CD 파이프라인의 경우, --check를 사용하여 버전이 오래되었을 때 실패하도록 설정할 수 있습니다:

npx spec-flow status --check

단일 서브시스템 (subsystem)에 집중하여 작업할 경우:

/feature "user profile editing" # 워크플로 시작
/feature continue # 중단 후 재개

여러 서브시스템에 걸친 복잡한 작업의 경우:

/epic "OAuth 2.1 authentication" # 멀티 스프린트 오케스트레이션 (Multi-sprint orchestration)
/epic continue # 에픽 (epic) 작업 재개

에픽 (Epics)은 잠긴 API 계약 (API contracts)을 가진 병렬 스프린트 (parallel sprints)로 분해되어, 병렬화를 통해 3~5배의 속도 (velocity)를 제공합니다.

전체 워크플로가 필요하지 않은 작은 변경 사항의 경우:

/quick "fix login button alignment"

명령어	기능
/feature "name"	기능 (Feature) 워크플로 시작
/epic "goal"	멀티 스프린트 에픽 (Epic) 시작
/quick "fix"	작은 변경 사항을 위한 빠른 경로
/help	문맥 인식 가이드

명령어	단계 (Phase)
/spec	명세서 (Specification) 생성
/plan	구현 계획 (Implementation Plan) 생성
/tasks	TDD 태스크로 세분화
/implement	태스크 실행
/optimize	품질 게이트 (Quality Gates) 실행
/ship	스테이징/운영 환경 배포

명령어	기능
/init-project	프로젝트 문서 생성
/init-preferences	워크플로 기본 설정 구성
/roadmap	GitHub Issues를 통한 기능 관리

슬래시 명령어 (Slash-command) 인터페이스에 대한 정보는 공개된 설치 워크플로 명령어 참조를 확인하세요. 설치 및 유지 관리 명령어를 실행하려면 npx spec-flow help를 실행하십시오.

/spec "user authentication"

다음 내용을 포함하는 spec.md를 생성합니다:

• Gherkin 형식을 사용한 사용자 시나리오 (User scenarios)
• 기능적 및 비기능적 요구사항 (Functional and non-functional requirements)
• 수락 기준 (Acceptance criteria)
• 성공 지표 (Success metrics)

/plan

다음 내용을 포함하는 plan.md를 생성합니다:

• 아키텍처 결정 사항 (Architecture decisions)
• 컴포넌트 세분화 (Component breakdown)
• 코드 재사용 기회 (Code reuse opportunities)
• 리스크 평가 (Risk assessment)

/tasks

다음 내용을 포함하는 tasks.md를 생성합니다:

• 20-30개의 구체적인 구현 태스크 (Implementation tasks)
• TDD 시퀀싱 (Red → Green → Refactor)
• 의존성 순서 (Dependency ordering)
• 태스크별 수락 기준 (Acceptance criteria per task)

/implement

다음 방식을 통해 태스크를 실행합니다:

• 테스트 우선 개발 (Test-first development)
• 전문 에이전트 (Specialist agents: 백엔드, 프론트엔드, 데이터베이스)
• 병렬 배치 실행 (Parallel batch execution)
• 자동 오류 복구 (Automatic error recovery)

/optimize

다음 병렬 점검을 실행합니다:

• 성능 벤치마크 (Performance benchmarks)
• 보안 스캐닝 (Security scanning)
• 접근성 감사 (Accessibility audits)
• 코드 리뷰 (Code review)
• 테스트 커버리지 검증 (Test coverage validation)

/ship

다음 사항을 처리합니다:

• 스테이징 배포 (Staging deployment)
• 검증 체크 (Validation checks)
• 운영 환경 승격 (Production promotion)
• 롤백 기능 (Rollback capability)

이것은 npx spec-flow init 실행 후의 전형적인 소비자 프로젝트 레이아웃입니다. Spec-Flow 자체의 소스 리포지토리(Source repo) 레이아웃은 아닙니다.

your-project/
├── .claude/
│ ├── commands/ # 슬래시 명령어
...

Spec-Flow는 Gemini CLI 확장 기능으로 설치하여 Gemini에서도 동일한 구조화된 워크플로우 (workflow)를 사용할 수 있습니다.

설치 (Install): # 프로젝트 루트 디렉토리 내에서 npx spec-flow install-gemini-extension

또는 프로젝트 내부에서 다음을 실행하세요: gemini extensions install .

사용 (Use): 이 확장 기능은 Gemini CLI 세션 내에서 동일한 슬래시 명령어 (/feature, /plan 등)를 직접 제공합니다. /feature "add user authentication"

기술 및 에이전트 (Skills & Agents): Gemini 확장 기능은 Spec-Flow의 에이전트 (agents)와 기술 (skills)을 Gemini 환경 내에서 작동하도록 자동으로 조정하여, backend-dev 또는 git-workflow-enforcer와 같은 특화된 페르소나 (personas)를 활용할 수 있게 합니다.

슬래시 명령어 지원을 갖춘 Claude Code, Git 2.39 이상, Python 3.10 이상, YAML 처리를 위한 yq 4.0 이상

Windows 사용자: 완전한 호환성을 위해 Git for Windows를 설치하세요.

가이드	설명
시작하기 (Getting Started)	단계별 튜토리얼
...

체크인된 예시 프로젝트 문서는 docs/examples/flightpro-sample-project/ 아래에 실시간으로 제공됩니다.

사용자 프로젝트는 설치 후 specs/NNN-feature/ 및 epics/NNN-epic/ 워크스페이스 (workspaces)를 생성합니다.

신뢰할 수 있는 단일 진실 공급원 (Source-of-Truth) 정리 및 정직한 엔진 노출 - 배포된 패키지를 저장소 (repo)의 실제 공개 및 내부 경계와 일치시킴

잠금된 도메인 계약 (Locked domain contract): 소스 저장소 소유권, 소비자 프로젝트 경계 및 표준 용어를 정의하기 위해 CONTEXT.md를 추가함
정직한 명령어 노출 (Truthful command surfaces): 공개 문서에서 이제 npx spec-flow ... 설치 명령어와 설치된 워크플로우 명령어를 명확하게 구분함
정직한 공유 엔진 (Honest shared engine): spec-cli.py는 이제 파일 누락으로 인한 오류 발생 대신, 계획된 노출 영역과 호환성 심 (compatibility shims)을 명시적으로 표시함
더 안전한 호환성 경로 (Safer compatibility path): tasks, validate, implement, preview를 위한 단계적 심 (shim) 엔트리포인트 (entrypoints)가 이제 구조화된 안내와 함께 깔끔하게 실패 처리됨

Token Bridge 패턴을 통한 shadcn/ui 통합 - OKLCH 토큰 + shadcn 호환 CSS 변수 생성

8가지 커스터마이징 옵션: 스타일 프리셋 (Style Preset), 기본 색상 (Base Color), 테마 모드 (Theme Mode), 아이콘 라이브러리 (Icon Library), 글꼴 패밀리 (Font Family), 테두리 반경 (Border Radius), 메뉴 색상 (Menu Color), 메뉴 액센트 (Menu Accent)
Token Bridge 패턴: OKLCH 토큰이 신뢰할 수 있는 단일 원천 (Source of Truth)으로 유지되며, shadcn CSS 변수 별칭 (Aliases)이 생성됨
Brownfield 스캐닝: 기존 색상 토큰을 자동 감지 및 통합
메뉴 테마 설정 (Menu theming): 배경, 호버 (Hover), 활성 (Active) 및 액센트 (Accent) 스타일을 위한 새로운 메뉴 전용 토큰 제공

Ultrathink 철학 체크포인트 - 모든 워크플로 단계에 내장된 심층 사고 (Deep thinking)

단계별 체크포인트: 다르게 생각하기 (Think Different, 사양 정의), 집착하고 단순화하기 (Obsess+Simplify, 계획), 무자비하게 단순화하기 (Simplify Ruthlessly, 작업), 코딩하지 말고 제작하기 (Craft Don't Code, 구현)
점진적 깊이: 사고 요구 사항이 증가함에 따라 사소함 (Trivial) → 표준 (Standard) → 복잡함 (Complex) → 에픽 (Epic) 단계로 진행
가정 인벤토리 (Assumption inventory): 설계 전 모든 사항에 대해 의문을 제기
복잡성 예산 (Complexity budgets): 각 새로운 컴포넌트에 대한 타당성 입증

엔드 투 엔드 (End-to-End) 워크플로 실행을 위한 자동 모드 - 중단 없이 전체 워크플로 실행

• --auto 플래그가 /feature 및 /epic 명령어에 추가됨

• 최적화 (Optimize) → 배포 (Ship) → 마무리 (Finalize) 과정을 자동으로 계속 진행

• 수동 승인 프롬프트 건너뛰기

• CI 통과 시 PR 자동 병합 (설정값에 의해 제어됨)

• 배포 단계를 위한 완전 자동 조종: /ship --auto

새로운 설정값 (Preferences): deployment.auto_ship, deployment.auto_merge, deployment.auto_finalize

완전 자동 조종 (Full autopilot): /feature "add auth" --auto 실행 시 전체 워크플로가 관리자 개입 없이 실행됨

CLI 버전 인식 - 자동 업데이트 감지를 통해 최신 상태 유지

• 버전 확인: npx spec-flow status를 통해 설치된 버전과 최신 버전 비교

• npm 레지스트리에서 정보를 가져오며, 오프라인 상황에서도 유연하게 처리

• 버전이 뒤처져 있을 경우 명확한 "업데이트 가능" 표시 제공

• CI/CD 통합: --check 플래그 사용 시 업데이트가 가능하면 종료 코드 1을 반환

버그 수정: healthCheck 변수 섀도잉 (Shadowing) 버그 수정

Git 워크트리 (Worktree) 통합 - 기능(Feature) 또는 에픽(Epic)별로 격리된 Git 상태를 사용하여 병렬 개발 지원

worktree-context.sh: 워크트리 (Worktree) 기반 개발을 위한 루트 오케스트레이션 (Orchestration) 유틸리티

• 기능 (Feature) 또는 에픽 (Epic)을 위한 자동 워크트리 생성
• 배포 (Ship) 워크플로우를 위한 병합 (Merge) 및 정리 (Cleanup) 기능
• cd-first 패턴을 사용하는 Task() 에이전트 컨텍스트 생성

워크트리 인식 에이전트 (Worktree-aware agents): 워커 (Worker) 에이전트가 격리된 워크트리 실행을 지원
명령어 통합 (Command integration): /feature, /implement-epic, /ship 명령어가 이제 워크트리를 생성하고 관리합니다.
기본 활성화 (Enabled by default): worktrees.auto_create: true 설정

• 병합 충돌 (Merge conflicts)을 약 90% 감소시킵니다.

자동 회귀 테스트 생성 (Automatic Regression Test Generation) - 재발 방지를 위해 버그를 테스트로 캡처

regression-test-generator 스킬: 프레임워크별 회귀 테스트 자동 생성

• 프레임워크 자동 감지 (Jest, Vitest, pytest, Playwright)
• 에러 ID 참조를 포함한 Arrange-Act-Assert 테스트 구조
• 테스트를 error-log.md 항목과 연결

테스트 실패 시 /debug 자동 호출: /implement 중 테스트가 실패하면 /debug가 자동으로 호출됩니다.

• 실패에 대한 회귀 테스트 생성 (단계 3.5)
• 테스트 참조 정보를 포함하여 error-log.md 업데이트

지속적 체크 (Continuous checks) 통합: Check 7/7은 테스트 실패 시 자동 디버그 (Auto-debug)를 트리거합니다.

/quick 명령어 - Task() 오케스트레이터 패턴 (Orchestrator Pattern) - 모든 워크플로우 명령어에 걸쳐 일관된 아키텍처 제공

quick-worker 에이전트: 원자적 (Atomic) 빠른 변경 실행을 위한 격리된 에이전트

• 도메인 감지 (Backend/Frontend/Test/Docs)
• 테스트 프레임워크 감지 및 실행
• 스타일 가이드 검증 (UI 변경 시)
• Conventional Message를 사용한 자동 커밋

구분자 기반 반환 (Delimiter-based returns): ---COMPLETED---, ---NEEDS_INPUT---, ---FAILED---

전체 Q&A 지원: 테스트 실패 결정 사항이 메인 컨텍스트로 배치(Batch) 처리됩니다.

명령형 Task() 아키텍처 (Imperative Task() Architecture) - 명령어가 이제 적절하게 격리된 에이전트를 생성(Spawn)합니다.

중대한 변경 사항 (Breaking Change): /feature 및 /epic 명령어가 명령형 Task() 생성을 사용하도록 재작성되었습니다. 단계별 에이전트(Phase agents)는 이제 구조화된 구분자(---COMPLETED---, ---NEEDS_INPUT---, ---FAILED---)를 반환합니다.

• 질문 일괄 처리 (Questions batching): 에이전트가 질문을 반환하면 메인 프로세스가 사용자에게 질문하고, 답변과 함께 에이전트를 재실행 (re-spawns)
• run_in_background: true를 통한 에픽 (epics) 단위의 병렬 스프린트 (sprint) 실행

초경량 오케스트레이터 패턴 (Ultra-lightweight Orchestrator Pattern)

• 디스크에서 상태를 읽고, 격리된 에이전트를 생성하며, 질의응답(Q&A)을 처리하고, 상태를 업데이트함
• 컨텍스트 (context)에 구현 세부 사항을 절대 포함하지 않음
• 무제한의 기능/에픽 복잡도 지원 (컨텍스트 오버플로 (context overflow) 없음)

업데이트된 에이전트 (Updated Agents)

• spec-agent.md, plan-agent.md: 구분자 (delimiter) 기반 반환 형식
• worker.md: WORKER_COMPLETED, WORKER_FAILED, ALL_DONE, BLOCKED 구분자 사용
• initializer.md: INITIALIZED, INIT_FAILED 구분자 사용

도메인 메모리 v2 (Domain Memory v2) - 완전한 단계 격리 (Full Phase Isolation) - 컨텍스트 오버플로를 방지하는 혁신적인 아키텍처

도메인 메모리 시스템 (Domain Memory System)

• 무제한 반복을 위한 디스크 기반의 지속적인 상태 관리
• 워커 (Workers)는 단 하나의 작업만 선택하여 구현, 테스트, 디스크 업데이트 후 종료
• 워커 간 공유 컨텍스트 제로 (공유 컨텍스트가 없어 오버플로 방지)
• 상태 관리를 위한 13가지 명령어로 구성된 CLI

단계 격리 패턴 (Phase Isolation Pattern)

• 모든 단계는 Task()를 통해 격리된 에이전트를 생성함
• 질문 일괄 처리 (Question batching): 에이전트가 질문을 반환하면 메인 프로세스가 사용자에게 질문하고, 에이전트가 재개함
• interaction-state.yaml을 통해 어느 지점에서든 재개 가능

프로젝트 설정 에이전트 (Project Setup Agents)

• /init-project, /prototype, /roadmap을 위한 하이브리드 패턴: 설문은 인라인(inline)으로 진행하고, 대규모 생성 작업은 격리하여 수행

mgrep 시맨틱 검색 (mgrep Semantic Search)

• 정확한 텍스트가 아닌 의미(meaning)로 코드 검색
• 중복 방지 기술의 기본 (PRIMARY) 검색 기능으로 통합됨
• 에이전트 부팅 절차(boot-up rituals)에 추가됨

품질 피드백 루프 시스템 (Quality Feedback Loop System) - 멀티 에이전트 투표, 지속적인 점검 및 영구적인 학습

멀티 에이전트 투표 (Multi-Agent Voting)

• 다양한 샘플링을 통한 오류 비상관화 (Error decorrelation) (MAKER 알고리즘)
• 코드 리뷰, 보안 감사, 파괴적 변경 (breaking changes)을 위해 k=2 전략을 사용하는 3개 에이전트 투표 수행
• 온도 (Temperature) 변화 (0.5, 0.7, 0.9)를 통해 에이전트 간의 오류를 비상관화함
• /optimize 단계에서 자동 실행되며, /review --voting을 통해 수동 실행 가능

지속적인 품질 점검 (Continuous Quality Checks)

• /implement 단계 중 경량화된 검증 수행

phase - 각 작업 배치(3-4개 작업) 이후 실행, 30초 미만의 성능 목표

• 6가지 검사: 린팅 (linting, 자동 수정), 타입 체크 (type checking), 단위 테스트 (unit tests), 커버리지 변화량 (coverage delta), 데드 코드 (dead code), 격차 탐지 (gap detection)
• 사용자 선택이 가능한 비차단형 (Non-blocking) 경고: 즉시 수정, 계속 진행, 또는 중단

점진적 품질 게이트 (Progressive Quality Gates)

• 워크플로 전반에 걸쳐 단계적으로 강화되는 세 가지 수준
• 레벨 1: 지속적 (Continuous) (각 배치 이후, 30초 미만, 경고 후 계속 진행)
• 레벨 2: 전체 품질 게이트 (Full quality gates) (/optimize 단계, 10-15분, 배포 차단)
• 레벨 3: 핵심 사전 점검 (Critical pre-flight) (/ship 단계, 2분 미만, 프로덕션 배포 차단)

온디맨드 리뷰 (On-Demand Review)

• 언제든 코드 리뷰를 수행할 수 있는 새로운 /review 명령어
• 빠른 리뷰 (단일 에이전트, 약 2-3분) 또는 종합 투표 리뷰 (3개 에이전트, 약 5-8분)
• 린팅 자동 수정, 파일:라인 참조 추출, 커버리지 격차 생성