Spec driven workflow

何时使用

当满足以下任一情况时采用本工作流：

• 用户要求在写代码前先写规约、定义验收标准，或推行规格优先（spec-first）开发。
• 新功能需要在实现前明确范围、约束与边界，避免范围蔓延。
• 需要从规格直接派生测试用例，把验收标准 1:1 转成测试。

铁律：无已批准规约，不写代码。没有例外，没有「快速原型」，没有「以后补文档」。 规约不是文档，而是契约：它定义系统 MUST、SHOULD、WILL NOT 做什么；每行代码可回溯到一条需求，每个测试可回溯到一条验收标准。不在规约里的，就不实现。

不该用的边界：

• 纯探索性 spike / 概念验证，需求尚不成形——先探索清楚再回到本流程。
• 事后补写文档来描述「已经做了什么」——那是文档不是规约，应改名为文档（见反模式 4）。
• 单行修复、纯重构、无行为变更的内部清理——直接走 TDD 重构即可。

步骤

六个阶段，每阶段有明确出口判据：

1. 收集需求：访谈用户（解决什么问题、谁是用户、成功长什么样、明确不做什么），阅读现有代码，识别约束与未知项。出口：能在 2 分钟内向不了解项目的人讲清这个功能。
2. 撰写规约：按九大必填小节填满模板，不留空白；为所有需求编号（FR-、NFR-、AC-、EC-、OS-）；精确使用 RFC 2119 关键词；验收标准用 Given/When/Then。出口：把规约交给没参加需求会的开发者，他无需追问即可实现。
3. 校验规约：运行 spec_validator.py 并过人工清单。出口：校验得分 ≥ 80 且人工清单全通过。
4. 生成测试：用 test_extractor.py 从验收标准抽取测试桩。每条 AC / EC 至少一个用例，测试只定义断言不含实现，初始必须全红（TDD 的 RED）。出口：得到一份每个测试都以「未实现」失败的测试文件。
5. 实现：一次只挑一条验收标准（从最简单起），用最小代码让其测试通过，跑全量测试无回归，提交，再挑下一条。出口：全部测试通过、全部 AC 满足。
6. 自审：过自审清单，任一项不过先修复再宣告完成。

指令

九大必填小节（不适用时写「N/A —— 原因」，证明考虑过而非遗漏）：

1. 标题与元数据（作者、日期、状态 Draft/In Review/Approved/Superseded、评审人）
2. 背景（为何存在，2-4 段，附指标/工单等证据）
3. 功能需求（RFC 2119 关键词，编号 FR-N，原子且可测）
4. 非功能需求（性能/安全/可访问性/可扩展/可靠，均带可度量阈值）
5. 验收标准（Given/When/Then，每条至少引用一个 FR-/NFR-）
6. 边界情况（编号 EC-N，覆盖每个外部依赖的失败模式）
7. API 契约（TypeScript 风格接口，覆盖成功与错误响应）
8. 数据模型（表格：字段、类型、约束；需求中每个实体都要有模型）
9. 范围之外（显式排除并说明理由，防止范围蔓延）

RFC 2119 关键词：MUST 绝对要求 / MUST NOT 绝对禁止 / SHOULD 推荐（省略需书面理由）/ MAY 可选（由实现者裁量）。

工具命令：

# 生成规约模板
python spec_generator.py --name "User Authentication" --description "OAuth 2.0 login flow"

# 校验规约完整度（0-100 分），严格模式
python spec_validator.py --file specs/auth.md --strict

# 从验收标准抽取测试用例
python test_extractor.py --file specs/auth.md --framework pytest --output tests/test_auth.py

有界自治——何时必须停下来升级（STOP & Ask）：检测到范围蔓延、对某需求的歧义超过 30%、需要破坏性变更（改既有 API/库 schema/公共接口）、触及安全（认证/授权/加密/PII）、性能特征无法度量、存在跨团队依赖。何时可自主继续：规约对当前任务清晰无歧义、所有 AC 已有通过测试而你在重构内部、变更非破坏性、实现是某条明确 AC 的直接翻译、错误处理沿用代码库既有模式。

升级时务必带方案，不要开放式提问：

## 升级：[简短标题]
**受阻于：** [需求 ID，如 FR-3]
**问题：** [具体、可回答的问题，不是「我该怎么办」]
**已考虑选项：**
  A. [选项] —— 优点：… 缺点：…
  B. [选项] —— 优点：… 缺点：…
**我的建议：** [A 或 B，附理由]
**等待的影响：** [在此解决前什么被阻塞？]

自审清单（标记完成前全部核对）：每条 AC 都有通过的测试；每个 EC 都有测试；无范围蔓延；API 契约与实现逐字段一致；每个错误响应都有触发它的测试；非功能需求有证据（基准/压测/profiling）；数据模型与库 schema 一致；范围之外的项确实没被实现。

示例

以「密码重置」功能为例：先在背景小节用工单与指标说明为何要做，再写 FR（如「FR-1：系统 MUST 在用户提交注册邮箱后发送一次性重置链接」），配套写非功能需求（如「NFR-1：重置邮件 MUST 在 < 30s 内发出」）。验收标准用 Given/When/Then：

AC-1（引用 FR-1）：Given 已注册用户在登录页点击「忘记密码」，When 输入正确邮箱并提交，Then 系统发送含有效期 15 分钟的一次性链接。

边界情况覆盖外部依赖失败，如「EC-1：邮件服务超时——系统 MUST 返回友好提示并允许重试」。随后 test_extractor.py 把每条 AC/EC 转成 pytest 桩（初始全红），实现阶段逐条点亮。

注意事项

避免以下反模式：

• 规约批准前就编码：评审会带出改动，你会得到实现了被否方案的代码。状态变为 Approved 前不开工。
• 含糊验收标准：「系统应工作良好」「UI 应响应迅速」无法测。每条 AC 必须机器可验证，写不出测试就重写标准。
• 缺失边界情况：只规定 happy path，错误路径靠开发现场发挥导致行为不一致。每个外部依赖至少给一个失败场景。
• 事后补规约：写于代码之后的不是规约，是文档，无法捕捉已冻结的设计错误——请改名为文档。
• 超规镀金：「顺手加了…」会引入未测、未评审的代码。不在规约里就别做，新功能另立规约。
• 验收标准无追溯：孤立的 AC 意味着要么缺需求要么该标准多余。每条 AC- MUST 至少引用一个 FR-/NFR-。
• 跳过校验：开工前必跑 spec_validator.py --strict 并修掉所有告警。

与 TDD 的衔接：本工作流在 Phase 4 产出测试桩（RED），之后交给 TDD 的红-绿-重构。规约告诉你测什么，TDD 告诉你怎么实现。

互见

• TDD 指南（tdd-guide）：红-绿-重构、覆盖率分析、框架特定测试模式（Jest/Pytest/JUnit），在本流程 Phase 4 之后接手。
• 聚焦修复（focused-fix）：当规约驱动的实现出现系统性问题时用于诊断。
• RAG 架构（rag-architect）：若功能涉及检索或知识系统，用它在规约内做技术设计。
• 参考资料：spec_format_guide.md（完整模板与示例）、bounded_autonomy_rules.md（停/继续决策矩阵）、acceptance_criteria_patterns.md（Given/When/Then 模式库）。

---

采编自 alirezarezvani/claude-skills（MIT 许可）。