SpecFlow

规范驱动开发，从想清楚到归档上线，一条流水线走完。

SpecFlow 把 OpenSpec（结构化需求规划）和 Superpowers（TDD、调试、代码审查等工程纪律）合并为一个工具：一个 CLI 负责确定性操作，一套跨 IDE 工作流技能负责 AI 编排，覆盖从探索需求到归档合并的完整生命周期。

| 环境 | 命令形式 | 详细指南 | |------|----------|----------| | Claude Code | /specflow:propose 等斜杠命令 | 本文 | | Cursor | specflow:propose 等命令 | Cursor 指南 | | OpenAI Codex | $specflow-propose 等技能 | Codex 指南 |

这是什么

用 AI 写代码时，常见两类问题：

1. 想不清楚就开始写 — 需求模糊、方案没比过、边界没定，返工多
2. 写完了对不上规格 — 没有可验收的 spec、变更难追溯、棕地项目更难接手

SpecFlow 的解法是把开发拆成有门禁的阶段，每个阶段产出可审查的 artifact（文档 + 规格），CLI 负责合并与校验，AI 技能负责按流程执行。

explore（可选）→ propose → refine → apply → review → test → verify → archive

棕地项目（已有代码库）不需要单独的「扫描」命令：用 explore 读代码定边界，或在 propose 的 Q&A 里描述现有行为 + 本次变更，由 delta spec 建立基线。

核心能力

| 能力 | 说明 | |------|------| | 结构化规划 | 一次 propose 产出 proposal、delta specs、design、tasks 四个 artifact | | 多轮精化 | refine 内部循环（≥2 轮），攻击性审查假设、边界与 scope | | 纪律化构建 | apply 先重写 tasks.md，再逐任务 TDD；design 有漏则回 refine | | 双重验收 | verify 对照 delta specs 与主 specs 做回归检查 | | 变更归档 | archive 自动 merge delta、移入 archive、可做 git 分支清理 | | 跨 IDE 一致 | Claude / Cursor / Codex 共享同一套技能与 prompt，parity 可校验 | | 确定性 CLI | 校验、合并、状态追踪、资产同步 — 不依赖 AI 猜 |

工作流程

阶段总览

┌─────────────────────────────────────────────────────────────────────────┐
│  explore [可选]   需求模糊时：读代码、比方案、定边界 → explore.md        │
│       ↓  handoff：explore.md Status 必须为 confirmed                    │
├─────────────────────────────────────────────────────────────────────────┤
│  propose          产出 proposal + delta specs + design + tasks          │
│       ↓                                                                 │
│  refine           ≥2 轮精化：挑战假设 / 新方案 / 探边界 / 质疑 scope     │
│       ↓                                                                 │
│  apply            Phase A 重写 tasks.md → Phase B 逐任务 TDD 执行         │
│       ↓                                                                 │
│  review → test → verify                                                 │
│       ↓                                                                 │
│  archive          delta merge 入主 specs，变更移入 archive/              │
└─────────────────────────────────────────────────────────────────────────┘

快捷通道：
  fix   — 修 Bug：调试 → TDD 修复 → 审查 → 测试 → 归档
  snap  — 事后补档：从 git diff 反推变更记录并归档

变更生命周期（phase）

每个 change 在 .specflow.yaml 中追踪 phase：

| phase | 含义 | 典型触发 | |-------|------|----------| | propose | 规划阶段（explore / propose） | specflow change new 默认值 | | refined | refine 收敛完成 | refine 结束后 | | apply | 代码已实现 | apply Phase B 完成后 | | archived | 已归档 | archive 完成后 |

specflow change archive 默认要求 phase=apply；可用 --force 跳过。老版本 change 若仍写 plan / built，CLI 读取时会自动映射为 propose / apply。

explore 门禁

• explore.md 中 **Status**: draft → propose 被阻止，需先确认方向
• **Status**: confirmed → propose 读取已确认结论并合成 artifact
• apply / refine 卡住时，可对子问题再次 explore（mid-change re-explore）

快速开始

前置依赖

• Node.js ≥ 20.19.0
• Git（worktree 与归档分支管理）
• 任选 AI 编码环境：Claude Code / Cursor / Codex

安装

# 推荐：npm 全局安装
npm install -g @gordon.gan/specflow

# 或从 GitHub 安装最新代码
npm install -g github:Gordon-Gan-Jiang/specflow

# 验证
specflow --version   # 当前 1.1.0
specflow --help

开发者本地调试：

git clone https://github.com/Gordon-Gan-Jiang/specflow.git
cd specflow && npm install && npm run build && npm link

在项目中初始化

cd your-project
specflow init              # 默认：Claude + Cursor
specflow init --ide codex  # 仅 Codex
specflow init --ide all    # Claude + Cursor + Codex

init 会创建 specflow/ 目录、写入 config.yaml，并按 --ide 生成对应托管资产（skills、commands、prompts 等），同时幂等地追加 .gitignore 忽略可再生的 prompts/schemas/templates。

跑通第一个变更

需求已清晰：

/specflow:propose "给用户管理模块加批量导入"
/specflow:refine
/specflow:apply
/specflow:verify
/specflow:archive

需求模糊：

/specflow:explore "不确定用 CSV 还是 Excel，也不清楚现有用户表结构"
# 确认 explore.md 后：
/specflow:propose
/specflow:refine
...

（Cursor 用 specflow:propose；Codex 用 $specflow-propose，其余类推。）

典型场景

新项目（greenfield）

需求清晰时直接从 propose 开始；每个阶段产出实质内容，refine 多轮打磨后再 apply。

棕地项目（brownfield）

specflow init

/specflow:explore "描述模糊问题或不确定的改法"    # 可选
/specflow:propose "描述已有行为 + 本次要改什么"
/specflow:refine
/specflow:apply
/specflow:archive

在 propose 阶段通过 delta spec 为将要改动的 capability 建立基线，无需单独扫描命令。

紧急修 Bug

/specflow:fix "登录接口 token 过期时返回 500 而不是 401"

包含：创建轻量变更 → 对照 specs 调试 → TDD 修复 → 审查 → 测试 → 归档。加 --urgent 可跳过审查。

同事没走流程，事后补档

/specflow:snap "重构了认证模块"

分析 git diff + log，反推变更记录，用户确认后归档。

IDE 工作流命令

共 10 个技能，命名因 IDE 而异：

| 阶段 | Claude Code | Cursor | Codex | |------|-------------|--------|-------| | 探索（可选） | /specflow:explore | specflow:explore | $specflow-explore | | 规划 | /specflow:propose | specflow:propose | $specflow-propose | | 精化 | /specflow:refine | specflow:refine | $specflow-refine | | 构建 | /specflow:apply | specflow:apply | $specflow-apply | | 审查 | /specflow:review | specflow:review | $specflow-review | | 测试 | /specflow:test | specflow:test | $specflow-test | | 验收 | /specflow:verify | specflow:verify | $specflow-verify | | 归档 | /specflow:archive | specflow:archive | $specflow-archive | | 修 Bug | /specflow:fix | specflow:fix | $specflow-fix | | 补档 | /specflow:snap | specflow:snap | $specflow-snap |

各命令职责

| 命令 | 做什么 | |------|--------| | explore | 读代码、比方案、定边界；产出 explore.md，confirmed 后 handoff 到 propose | | propose | 一次产出 proposal、delta specs、design、tasks（第一轮深度思考，非占位骨架） | | refine | 内部多轮循环（≥2 轮，AI 判断收敛）；可更新任意 artifact | | apply | Phase A 用 writing-plans 规则重写 tasks.md；Phase B subagent TDD 逐任务执行 | | review | 代码审查，对照 specs 检查回归 | | test | 单元 + 集成 + E2E + 回归测试 | | verify | Pass 1：delta specs 验收；Pass 2：主 specs 回归（无基线时显式 skipped） | | archive | 归档变更、delta merge、git 分支清理；默认要求 phase=apply | | fix | 修 Bug 一条龙 | | snap | 从 git 历史反推变更并归档 |

v1.0.1 起命令已重命名（对齐 OpenSpec 术语）：plan→propose、build→apply、done→archive。.specflow.yaml 的 phase 枚举同步为 propose/refined/apply/archived（读取时兼容旧值 plan/built）。

CLI 命令

CLI 从当前目录向上查找项目根（识别 specflow/config.yaml），类似 git 行为。

项目初始化

| 命令 | 说明 | |------|------| | specflow init [--ide claude\|cursor\|codex\|both\|all] | 初始化项目目录与 IDE 托管资产 | | specflow sync [--ide ...] [--no-parity-strict] | 从已安装的 specflow 包同步/更新 IDE 资产（升级后用） | | specflow doctor [--parity] [--json] | 诊断 IDE 资产是否完整、迁移状态是否正常 | | specflow parity-report [--json] | 对比 Claude / Cursor / Codex 能力是否一致 |

变更管理

| 命令 | 说明 | |------|------| | specflow change new <名称> | 创建新变更（.specflow.yaml 默认 phase: propose） | | specflow change status <名称> | 查看 artifact 完成状态 | | specflow change phase <名称> | 查看当前 phase | | specflow change phase <名称> --set <phase> | 设置 phase（propose \| refined \| apply \| archived） | | specflow change archive <名称> [--force] | 归档变更；--force 跳过 phase=apply 门禁 |

规格与指令

| 命令 | 说明 | |------|------| | specflow validate <文件> | 校验 spec 文件格式（WHEN/THEN scenario 等） | | specflow instructions <artifact> <change> | 查看某 artifact 的创建指令 |

关键概念

Specs — 唯一事实来源

存放在 specflow/specs/，描述各 capability 的行为规格：

### Requirement: 用户登录
系统应当支持通过邮箱和密码进行用户认证。

#### Scenario: 登录成功
- **WHEN** 用户提交有效凭据
- **THEN** 系统返回认证 token

Changes — 一次功能或修复

存放在 specflow/changes/<name>/：

| 文件 | 作用 | |------|------| | explore.md | 可选；探索结论，Status 控制 propose 门禁 | | proposal.md | 为什么做、做什么 | | specs/ | delta specs（对主 specs 的增量变更） | | design.md | 技术方案 | | tasks.md | 实施任务清单（带 checkbox） | | .specflow.yaml | 变更元数据（含 phase） |

归档后 delta 自动 merge 进 specflow/specs/，change 移入 specflow/changes/archive/。

Delta Specs — 四种操作

## ADDED Requirements      # 新增
## MODIFIED Requirements   # 修改（须写完整更新内容）
## REMOVED Requirements    # 删除（须说明原因与迁移）
## RENAMED Requirements    # 重命名（FROM / TO）

目录结构

specflow init 后项目新增（按 --ide 不同，IDE 目录有所差异）：

your-project/
├── specflow/                    # 规格与变更（应纳入 git）
│   ├── config.yaml
│   ├── specs/                   # 主 specs（Source of Truth）
│   └── changes/
│       ├── <name>/              # 活跃变更
│       │   ├── explore.md       # 可选
│       │   ├── proposal.md
│       │   ├── specs/
│       │   ├── design.md
│       │   ├── tasks.md
│       │   └── .specflow.yaml
│       └── archive/             # 已归档变更
│
├── .claude/                     # Claude Code（--ide 含 claude 时）
│   ├── skills/specflow-*/
│   ├── commands/specflow/
│   └── specflow/                # prompts/schemas/templates（可再生，gitignore）
│
├── .cursor/                     # Cursor（--ide 含 cursor 时）
│   ├── skills/specflow-*/
│   ├── commands/specflow/
│   └── specflow/
│
└── .agents/                     # Codex（--ide 含 codex 时）
    ├── skills/specflow-*/
    └── specflow/

Git 建议：

• 跟踪：specflow/、各 IDE 的 skills/ 与 commands/specflow/
• 忽略：各 IDE 下可再生的 specflow/{prompts,schemas,templates}/（init 自动追加）

架构

三层分离，各司其职：

┌──────────────────────────────────────────────┐
│  CLI 层（TypeScript，确定性）                  │
│  文件操作、校验、delta merge、归档、资产同步    │
├──────────────────────────────────────────────┤
│  SKILL.md 层（编排）                          │
│  阶段划分、hard gate、用户确认点、按需加载 prompt │
├──────────────────────────────────────────────┤
│  Prompts 层（执行指令）                       │
│  各阶段具体操作：写 proposal、TDD、审查等       │
└──────────────────────────────────────────────┘

• 渐进加载：SKILL.md 保持精简，prompt 按阶段 Read，避免 context 膨胀
• Hard Gate 双重声明：编排层与 prompt 层同时约束关键门禁
• CLI 不做 AI 逻辑：文本合并与格式校验由代码精确执行

维护与升级

升级全局 specflow 后，在项目里同步资产：

specflow sync --ide all

检查资产健康与跨 IDE 一致性：

specflow doctor --parity
specflow parity-report

重新初始化（init 检测到已初始化会拒绝，需先删除 specflow/config.yaml 等标记文件）：

rm -rf specflow/config.yaml .claude/specflow/   # 按需清理其他 IDE 目录
specflow init

故障排查

| 现象 | 处理 | |------|------| | specflow: command not found | 确认 npm install -g 成功；检查 npm config get prefix/bin 是否在 PATH | | No specflow project found | 确认已 specflow init 且 specflow/config.yaml 存在 | | Change "xxx" already exists | 换名称或先归档已有变更 | | propose 被 explore 阻止 | 将 explore.md 的 **Status** 改为 confirmed | | archive 拒绝（phase 不对） | 完成 apply 使 phase=apply，或 specflow change archive --force | | Node 版本不兼容 | 需要 ≥ 20.19.0：nvm install 20 && nvm use 20 | | parity-report FAIL | 运行 specflow sync --ide all 后重试 specflow doctor --parity |

来源与许可

基于两个开源项目（均为 MIT）：

• OpenSpec — artifact graph、delta merge、validation
• Superpowers — brainstorming、TDD、debugging、code review

来源内容已按 SpecFlow 风格改写，通过 <!-- SOURCE: ... --> 标注出处。

许可证：MIT