Spec-Flow - Structured Development Workflow

Structured workflow for complex feature development. Creates living documentation that guides implementation and serves as team reference.

Core Principles

1. One phase at a time — NEVER generate documents for subsequent phases in advance
2. Mandatory confirmation — After each phase, STOP and wait for user confirmation
3. User-driven progression — Only proceed when user says "continue"/"ok"/"next"/"继续"/"好"

Parameters

参数	说明
--fast	跳过逐阶段确认，一次性生成所有文档（最后整体确认）
--skip-design	跳过 Design 阶段（简单功能，架构显而易见时）

Language Rule

所有生成的 .md 文件必须使用中文。

Interaction Rules

Load references/interaction-rules.md for detailed confirmation templates and prohibited behaviors.

---

Five-Phase Workflow

Copy this checklist and check off items as you complete them:

Spec-Flow Progress:

• Phase 0: Initialize ⚠️ REQUIRED

  • 0.1 Run scripts/init-spec-flow.sh <feature-name> or create .spec-flow/active/<feature>/
  • 0.2 Check if .spec-flow/steering/ exists — if so, read for project context
  • 0.3 问自己：这个功能的核心价值是什么？用一句话能说清吗？

• Phase 1: Proposal ⚠️ REQUIRED

  • 1.1 Create .spec-flow/active/<feature>/proposal.md using templates/proposal.md.template
  • 1.2 包含：Background, Goals, Non-Goals, Scope, Risks, Open Questions
  • 1.3 问自己：有没有隐含的需求没写出来？
  • 1.4 问自己：Non-Goals 是否足够明确？能防止 scope creep 吗？
  • 1.5 ⏸️ 确认节点 — 等待用户确认后继续

• Phase 2: Requirements

  • 2.1 Create .spec-flow/active/<feature>/requirements.md using templates/requirements.md.template
  • 2.2 Load references/ears-format.md — 使用 EARS 格式编写需求
  • 2.3 包含：FR-xxx 功能需求, NFR-xxx 非功能需求, AC-xxx 验收标准
  • 2.4 问自己：每条需求都是可测试的吗？
  • 2.5 问自己：边界情况覆盖了吗？错误场景呢？
  • 2.6 ⏸️ 确认节点 — 等待用户确认后继续

• Phase 3: Design（除非 --skip-design）

  • 3.1 Create .spec-flow/active/<feature>/design.md using templates/design.md.template
  • 3.2 包含：Architecture (Mermaid), Components, API, Data Model, Error Handling
  • 3.3 问自己：这个设计能满足所有 requirements 吗？逐条对照
  • 3.4 问自己：有没有更简单的方案？过度设计了吗？
  • 3.5 ⏸️ 确认节点 — 等待用户确认后继续

• Phase 4: Tasks

  • 4.1 Create .spec-flow/active/<feature>/tasks.md using templates/tasks.md.template
  • 4.2 Load references/task-decomposition.md — 遵循任务拆解规范
  • 4.3 每个任务：1-2 tool calls 可完成，标注复杂度 Low/Medium/High
  • 4.4 分组：Setup → Implementation → Testing → Documentation
  • 4.5 问自己：任务之间的依赖关系对吗？有没有可以并行的？
  • 4.6 ⏸️ 确认节点 — 等待用户确认后继续

• Phase 5: Implementation

  • 5.1 Load references/execution-modes.md — 确认执行模式
  • 5.2 默认 Step Mode（逐任务确认），用户可切换 Batch/Phase Mode
  • 5.3 每个任务执行前：读 tasks.md → 检查依赖 → 读 design.md
  • 5.4 每个任务执行后：更新 tasks.md 状态（- [ ] → - [x]）
  • 5.5 全部完成后：归档到 .spec-flow/archive/

---

Directory Structure

.spec-flow/
├── steering/           # 全局项目上下文（可选）
│   ├── constitution.md
│   ├── product.md
│   ├── tech.md
│   └── structure.md
├── active/             # 进行中
│   └── <feature>/
│       ├── proposal.md
│       ├── requirements.md
│       ├── design.md
│       └── tasks.md
└── archive/            # 已完成

Steering Documents (Optional)

Document	Purpose	Template
constitution.md	项目治理原则	templates/steering/constitution.md.template
product.md	产品愿景、目标用户	templates/steering/product.md.template
tech.md	技术栈、约束	templates/steering/tech.md.template
structure.md	代码组织、命名规范	templates/steering/structure.md.template

Phase Transitions

From	To	Condition
Proposal	Requirements	Proposal approved, questions resolved
Requirements	Design	Requirements complete, testable
Requirements	Tasks	--skip-design, simple feature
Design	Tasks	Design approved
Tasks	Implementation	Tasks confirmed
Implementation	Done	All tasks complete → archive

Compatibility

Works with any AI agent that supports Skills format: Claude Code, Blade, OpenClaw, Cursor, Windsurf, etc.