spec-driven-workflow

规范驱动工作流 — POWERFUL

概述

规范驱动工作流强制执行一条不可协商的规则：在编写任何代码之前先编写规范。 不是同时，不是之后，而是之前。

这不是文档，而是一份契约。规范定义了系统必须（MUST）做什么、应该（SHOULD）做什么，以及明确不会（WILL NOT）做什么。你编写的每一行代码都可以追溯到规范中的某条需求。每一个测试都可以追溯到某条验收标准。如果规范中没有，它就不会被构建。

为什么规范优先很重要

1. 减少返工。 60% 至 80% 的缺陷源于需求而非实现。在规范中发现歧义只需几分钟，而在生产环境中发现则需要数天。
2. 迫使思路清晰。 如果你无法用平实的语言写出系统应该做什么，那么你对问题的理解就还不足以开始编写代码。
3. 支持并行。 规范一经批准，前端、后端、QA 和文档团队就可以同时开始工作。
4. 建立问责机制。 规范即完成的定义。对于某个功能是否"完成"不存在争议：要么满足验收标准，要么不满足。
5. 直接支撑 TDD。 采用 Given/When/Then 格式的验收标准可以一对一转化为测试用例。规范本身就是测试计划。

铁律

NO CODE WITHOUT AN APPROVED SPEC.
NO EXCEPTIONS. NO "QUICK PROTOTYPES." NO "I'LL DOCUMENT IT LATER."

如果规范尚未编写、评审并批准，实现工作就不应开始。没有例外。

---

规范格式

每份规范都遵循以下结构。所有章节都不是可选的：如果某一章节不适用，请写明"N/A — [原因]"，以便评审者知道它已被考虑过，而不是被遗忘。

必填章节

#	章节	关键规则
1	标题与元数据	作者、日期、状态（草稿/评审中/已批准/已被取代）、评审人
2	背景	说明此功能存在的原因。2 至 4 段，并附有证据（指标、工单）。
3	功能需求	使用 RFC 2119 关键词（MUST/SHOULD/MAY）。编号为 FR-N。每条需求都是原子化且可测试的。
4	非功能需求	性能、安全、无障碍、可扩展性、可靠性——均需有可衡量的阈值。
5	验收标准	采用 Given/When/Then 格式。每条验收标准至少引用一个 FR-* 或 NFR-*。
6	边界情况	编号为 EC-N。涵盖每个外部依赖的故障模式。
7	API 契约	采用 TypeScript 风格的接口定义。涵盖成功与错误响应。
8	数据模型	以表格形式列出字段、类型、约束。需求中出现的每个实体都必须有对应的模型。
9	范围之外	明确列出排除项及其原因。防止实现过程中出现范围蔓延。

RFC 2119 关键词

关键词	含义
MUST	绝对要求。缺少则不符合规范。
MUST NOT	绝对禁止。
SHOULD	推荐要求。仅在有书面理由时才可省略。
MAY	可选。由实现者自行决定。

完整模板（包含逐节示例、好与坏的需求写法，以及功能类型模板，如 CRUD、集成、迁移）请参阅 spec_format_guide.md。

完整的 Given/When/Then 验收标准模式库（涵盖身份认证、CRUD、搜索、文件上传、支付、通知和无障碍场景）请参阅 acceptance_criteria_patterns.md。

---

有限自主规则

这些规则定义了 Agent（人类或 AI）在什么情况下必须停止并寻求指导，以及在什么情况下可以独立继续推进。

遇到以下情况时停止并询问：

1. 检测到范围蔓延。 实现需要规格说明中没有的内容。即使看起来显然需要，也要停止。规格说明可能是有意排除的。

2. 歧义超过 30%。 如果对于某项需求，你无法从规格说明中确定正确行为的比例超过 30%，说明规格说明不完整。不要猜测。

3. 需要破坏性变更。 实现会改变现有 API 契约、数据库 schema 或公共接口。务必上报。

4. 安全影响。 任何涉及身份验证、授权、加密或 PII 处理的变更，都需要明确批准。

5. 性能特征未知。 如果某项需求写着"MUST 在 < 500ms 内完成"，但你没有办法测量或保证这一点，应在实现猜测性方案之前上报。

6. 跨团队依赖。 如果规格说明要求与其他团队或服务协调，在基于其构建之前先确认该依赖。

以下情况可自主继续：

1. 规格说明对当前任务清晰且无歧义。
2. 所有验收标准都有通过的测试，且你只是在重构内部实现。
3. 变更不破坏兼容性，即没有公共 API、schema 或行为变更。
4. 实现是对一条定义明确的验收标准的直接翻译。
5. 错误处理遵循代码库中已有文档记录的既定模式。

上报流程

当你必须停止时，请提供：

## Escalation: [Brief Title]

**Blocked on:** [requirement ID, e.g., FR-3]
**Question:** [Specific, answerable question — not "what should I do?"]
**Options considered:**
  A. [Option] — Pros: [...] Cons: [...]
  B. [Option] — Pros: [...] Cons: [...]
**My recommendation:** [A or B, with reasoning]
**Impact of waiting:** [What is blocked until this is resolved?]

上报时必须附带建议，绝不能只提出开放式问题，始终要给出选项。

完整决策矩阵请参阅 references/bounded_autonomy_rules.md。

---

工作流 —— 6 个阶段

阶段 1：收集需求

目标： 理解需要构建什么以及为什么要构建。

1. 访谈用户。 询问：
   • 这要解决什么问题？
   • 用户是谁？
   • 成功是什么样子？
   • 明确不应该构建什么？
2. 阅读现有代码。 在提出变更之前先理解当前系统。
3. 识别约束。 性能预算、安全要求、向后兼容性。
4. 列出未知项。 每个未知项都是风险。现在就把它们暴露出来，而不是等到实现阶段。

退出标准： 你能在 2 分钟内向一个不了解该项目的人讲清楚这个功能。

阶段 2：编写规格说明

目标： 按照上文的规格说明格式，产出一份完整的规格说明文档。

1. 填写模板中的每个章节，不留空白章节。
2. 为所有需求编号（FR-、NFR-、AC-、EC-、OS-*）。
3. 精确使用 RFC 2119 关键字。
4. 以 Given/When/Then 格式编写验收标准。
5. 用类 TypeScript 的类型定义 API 契约。
6. 在"范围之外"中列出明确的排除项。

退出标准： 规格说明可以交给一位未参加需求会议的开发者，他们无需提出澄清问题即可实现该功能。

阶段 3：验证规格说明

目标： 验证规格说明完整、一致且可实现。

对规格说明文件运行 spec_validator.py：

python spec_validator.py --file spec.md --strict

人工验证检查清单：

• 每条功能需求至少对应一条验收标准
• 每条验收标准都可测试（没有主观性语言）
• API 契约覆盖需求中提到的所有端点
• 数据模型覆盖需求中提到的所有实体
• 边界情况覆盖每个外部依赖的故障模式
• 范围之外明确列出了曾被考虑并被否决的内容
• 非功能需求具有可衡量的阈值

退出标准： 规格说明在 validator 中得分不低于 80，且人工检查清单全部通过。

Phase 4: 生成测试

目标: 在编写实现代码之前,从验收标准中提取测试用例。

针对已批准的规格说明运行 test_extractor.py:

python test_extractor.py --file spec.md --framework pytest --output tests/

1. 每条验收标准对应一个或多个测试用例。
2. 每个边界情况对应一个测试用例。
3. 测试为桩代码:定义断言,但不包含实现。
4. 所有测试在初始状态下都必须失败(TDD 的红灯阶段)。

退出标准: 你已拥有一个测试文件,其中每个测试都以 "not implemented" 或同等信息失败。

Phase 5: 实现

目标: 编写代码,使失败的测试逐条通过,每次处理一条验收标准。

1. 选择一条验收标准(从最简单的开始)。
2. 用最少的代码使其对应的测试通过。
3. 运行完整测试套件,确保没有回归。
4. 提交。
5. 选择下一条验收标准,重复上述步骤。

规则:

• 不要实现规格说明中没有的任何内容。
• 在所有验收标准通过之前,不要进行优化。
• 在所有验收标准通过之前,不要进行重构。
• 如果发现遗漏的需求,停止并先更新规格说明。

退出标准: 所有测试通过。所有验收标准均已满足。

Phase 6: 自我审查

目标: 在标记完成之前,验证实现与规格说明一致。

按照下方的自我审查清单逐项检查。如有任何一项不通过,先修复后再宣布任务完成。

---

自我审查清单

在将任何实现标记为完成之前,请验证以下全部内容:

• 每条验收标准都有一个通过的测试。 没有例外。如果存在 AC-3,就必须有针对 AC-3 的测试且该测试通过。
• 每个边界情况都有测试。 EC-1 到 EC-N 都有对应的测试用例。
• 没有范围蔓延。 实现不包含规格说明中没有的功能。如果添加了内容,要么更新规格说明,要么将其移除。
• API 契约与实现一致。 代码中的请求/响应结构与规格说明完全一致。字段名、类型、状态码,全部一致。
• 已测试错误场景。 规格说明中定义的每个错误响应,都有一个能够触发它的测试。
• 已验证非功能性需求。 如果规格说明要求小于 500ms,则需要有证据(基准测试、负载测试、性能分析)表明满足该阈值。
• 数据模型一致。 数据库 schema 与规格说明相符,没有多余的列,也没有缺失的约束。
• 未构建范围外的内容。 再次确认“范围外”部分的内容没有混入实现中。

---

与 TDD 指南的整合

规格驱动工作流与 TDD 相互补充,而非相互竞争:

Spec-Driven Workflow          TDD (Red-Green-Refactor)
─────────────────────         ──────────────────────────
Phase 1: Gather Requirements
Phase 2: Write Spec
Phase 3: Validate Spec
Phase 4: Generate Tests  ──→  RED: Tests exist and fail
Phase 5: Implement       ──→  GREEN: Minimal code to pass
Phase 6: Self-Review     ──→  REFACTOR: Clean up internals

交接: 规格驱动工作流产出测试桩(第 4 阶段)。之后由 TDD 接手。规格说明告诉你要测试什么(WHAT),TDD 告诉你如何实现(HOW)。

以下场景使用 engineering-team/tdd-guide:

• 红-绿-重构循环的纪律执行
• 覆盖率分析与缺口检测
• 特定框架的测试模式(Jest、Pytest、JUnit)

以下场景使用 engineering/spec-driven-workflow:

• 在构建之前先定义要构建的内容
• 编写验收标准
• 完整性校验
• 范围控制

---

示例

一个完整的示例(包含已提取测试用例的密码重置规格说明)可在 spec_format_guide.md 中查看。它展示了全部 9 个章节、需求编号、验收标准、边界情况,以及由 test_extractor.py 生成的对应 pytest 桩代码。

---

反模式

1. 在规格说明获批之前编码

症状: "规格说明还在评审中,我先开始写代码。" 问题: 评审必然会带来修改,到那时你已经写好的代码实现的是一个被否决的设计。 规则: 只有当规格说明状态为 "Approved" 时,才可以开始实现。

2. 验收标准含糊

现象： "系统应该运行良好"或"界面应该响应迅速"。 问题： 无法测试。"良好"是什么意思？"响应迅速"是什么意思？ 规则： 每条验收标准都必须能被机器验证。如果无法为其编写测试，就重写该标准。

3. 缺少边界情况

现象： 只规定了正常路径，没有规定错误路径。 问题： 开发者会临时自行设计错误处理，导致行为不一致。 规则： 对于每个外部依赖（API、数据库、文件系统、用户输入），至少规定一个失败场景。

4. 将规格说明当作事后文档

现象："功能已经做完了，现在来写规格说明。" 问题： 这属于文档，而非规格说明。它描述的是已经构建的内容，而不是应该构建的内容。由于设计已经定型，它无法发现设计错误。 规则： 如果规格说明是在代码之后编写的，它就不是规格说明。请将其重新标注为文档。

5. 超出规格的过度开发

现象："我顺手还加上了……" 问题： 未经测试的代码，未经评审的设计，"附加"功能中可能潜藏隐蔽的缺陷。 规则： 不在规格说明中的内容不予构建。额外功能需单独提交新的规格说明。

6. 验收标准缺少需求可追溯性

现象： AC-7 存在，但未引用任何 FR-* 或 NFR-。 问题： 孤立的标准意味着要么缺少需求，要么该标准本身不必要。 规则： 每个 AC- 必须至少引用一个 FR-* 或 NFR-*。

7. 跳过验证

现象："规格说明看起来没问题，直接开始吧。" 问题： 实施过程中才发现的缺失章节会造成阻塞性延误。 规则： 在开始实施前，务必运行 spec_validator.py --strict，并修复所有警告。

---

交叉引用

• engineering-team/tdd-guide：红-绿-重构循环、测试生成、覆盖率分析。在本工作流的第 4 阶段之后使用。
• engineering/focused-fix：深入的功能修复。当基于规格说明的实现存在系统性问题时，使用 focused-fix 进行诊断。
• engineering/rag-architect：如果功能涉及检索或知识库系统，使用 rag-architect 进行规格说明范围内的技术设计。
• references/spec_format_guide.md：包含逐节说明的完整模板。
• references/bounded_autonomy_rules.md：关于何时停止、何时继续的完整决策矩阵。
• references/acceptance_criteria_patterns.md：用于编写 Given/When/Then 标准的模式库。

---

工具

脚本	用途	关键参数
spec_generator.py	根据功能名称或描述生成规格说明模板	--name、--description、--format、--json
spec_validator.py	验证规格说明的完整性（0-100 分）	--file、--strict、--json
test_extractor.py	从验收标准中提取测试桩	--file、--framework、--output、--json

# Generate a spec template
python spec_generator.py --name "User Authentication" --description "OAuth 2.0 login flow"

# Validate a spec
python spec_validator.py --file specs/auth.md --strict

# Extract test cases
python test_extractor.py --file specs/auth.md --framework pytest --output tests/test_auth.py