spec-driven-development

规格驱动开发

概览

SDD 将规格作为事实来源——代码服务于规格，而不是反过来。不要再用模糊的描述提示 AI，然后寄希望于得到正确的结果；而是先定义精确的规格，再让 AI 严格按照规格生成代码。

没有规格时，AI 会悄无声息地做出成千上万次微小决策。有了规格，这些决策就由你明确做出，而且是在编写任何代码之前。正因如此，需求转向时，只需系统化地重新生成，而不必手动重写。

快速开始

1. /sdd:init — 创建 constitution.md（每个项目只需一次，在编写任何功能规格之前）
2. /sdd:research [description] — 梳理现有代码的工作方式，并引用 file:line（全新项目可跳过）
3. 在编写任何 AC 之前，明确并纠正 AI 的隐含假设
4. /sdd:specify [description] — 生成 spec.md，其中包含按 MoSCoW 优先级排序的 AC
5. 遵循各个关卡：澄清 → 规划 → 任务 → 实施 → 验证；每个关卡都需获得人工批准

分步说明：references/workflow-phases.md。

适用场景

以下情况表明需要采用 SDD：

• AI 忽略约束，或生成的代码不符合需求
• 相同的提示词在不同会话中产生不同的实现
• 需求复杂，涉及多个利益相关方或横切关注点
• 团队需要在编写代码前形成共同的技术理解
• 功能涉及身份验证、数据模型、API 契约或数据库架构

以下情况完全跳过： 单行修复、拼写错误、一次性原型，以及持续时间不足一天的个人探索性试验。

选择流程级别

并非每项变更都需要相同的流程。选择能够覆盖风险的最轻量级别。

	S — 轻量	M — 标准	L — 完整
适用场景	一个会话内完成、≤3 个文件、不涉及架构／契约／身份验证变更	新增端点、表或用户可见行为；跨多个会话	身份验证、支付、迁移、受监管领域、陌生代码
产物	问题或 PR 正文中的 AC	spec.md、plan.md、contracts/、tasks.md	+ research.md、decision_log.md、walkthrough.md
关卡	合并前自检	1、2、3、5	0、R、1–5、C
审查者	无	可选	必需

决策规则： 从 M 级开始。只有在以下条件全部满足时才降至 S 级——一个会话内完成、≤3 个文件、不改变契约或架构、可轻松回滚。如果以下条件中任意一项满足，则升至 L 级——涉及身份验证或支付、不可逆的数据迁移、受监管领域，或通话中的人都不熟悉相关代码。

两种失败模式的代价相同：对 S 级变更采用 L 级流程会导致“淹没在 Markdown 中”，而对 L 级变更采用 S 级流程正是这项技能要解决的问题。决胜因素是可逆性，而非规模。

级别针对每项变更，而非整个项目。执行过程中升级很正常——例如发现架构变更后，将 S 级提升到 M 级。降级则不然：这会舍弃你已经认定必不可少的关卡。

关键实践：重新表述模糊需求

编写任何 AC 之前，都要将模糊需求转化为可衡量的目标——“让它更快”应改为“在 4G 连接下 LCP < 2.5s”。如果无法为某条 AC 编写一个会失败的测试，这条 AC 就不够具体。 转换示例： references/artifact-templates.md → 编写具体的验收标准。

---

目录结构

constitution.md            # Immutable project principles (one per project)

specs/
  [feature-branch-name]/
    research.md        # How the system works TODAY, cited file:line   (0.5)
    spec.md            # Requirements — WHAT and WHY, MoSCoW           (1)
    plan.md            # Implementation strategy — HOW                 (2)
    data-model.md      # Entities, relationships, schemas              (2)
    contracts/         # Interfaces — LOCKED after Gate 2              (2)
    tasks.md           # Atomic executable task list                   (3)
    progress.md        # Optional: state across context resets         (4)
    validation.md      # Traceability matrix                           (5)
    walkthrough.md     # Optional: narration for reviewers             (5)
    decision_log.md    # Optional: rationale for key decisions
  archive/             # Completed specs, kept after the feature ships

每个产物也都是一个压缩检查点——将某个阶段繁杂的探索提炼成下一阶段唯一需要查看的文本。

---

阶段 0 — 章程 (每个项目只需一次)

调用： /sdd:init → 在项目根目录创建 constitution.md。

这是一份带版本管理的文档，记录适用于每项功能的不可变约束：架构原则、技术栈、安全约束、命名约定，以及明确禁止的模式。禁止 AI Agent 违反这些约束；每次实施提示词中都会完整包含该文档。

只有在项目的根本决策发生变化时才更新——绝不因单个功能而更新。

---

阶段 0.5 — 调研 (按功能视情况执行)

调用： /sdd:research [feature description] → specs/[feature]/research.md

在编写任何需求之前，对系统相关部分的当前工作方式绘制一份精简图谱。

在以下情况下执行： 功能涉及你未编写或已不记得的代码、存在多种有效架构，或这项工作属于重构或迁移。在以下情况下跳过： 绿地代码，或你能凭记忆说出所有接触点。

四条规则：

• 每项结论都要引用 file:line。 没有引用的发现就是猜测。
• 将繁杂工作交给子 Agent。 Glob、grep 和完整文件读取都在隔离上下文中运行；只返回精简后的摘要。
• 只描述现状，绝不描述应有的样子。 需求属于阶段 1。
• 控制在约 200 行以内。 超出后就是原始转储，而非精简摘要。

为什么这个阶段的杠杆效益最高： 审查约 200 行调研内容，可以避免写出数千行错误代码；审查代码则能一次避免一行错误代码。Gate R 是唯一一个值得花时间亲自阅读实际代码的关卡。

详情：references/workflow-phases.md → Phase 0.5。

---

5 阶段工作流 (按功能执行)

阶段	调用	读取	产出	关卡
1 — 规格说明	/sdd:specify [description]	research.md、用户意图	spec.md	Gate 1
1b — 澄清	/sdd:clarify	spec.md	已解决的 [NEEDS CLARIFICATION]、新增边界情况验收标准	（Gate 1 的一部分）
2 — 规划	/sdd:plan	spec.md、constitution.md、research.md	plan.md、data-model.md、contracts/	Gate 2
3 — 任务拆分	/sdd:tasks	plan.md、contracts/	tasks.md	Gate 3
4 — 实现	每个任务调用 /sdd:next-task	一个任务及其验收标准和契约	代码、测试、提交	Gate 4（每个任务）
5 — 验证	/sdd:validate	所有产物及代码	可追溯性矩阵、偏差报告、演练	Gate 5 + Gate C

每个关卡都是人工审批点。 AI 不能批准自己的输出。Gate 0、R、1–5 和 C 的完整检查清单见 references/quality-gates.md，其中还包括 /sdd:checklist [domain]——按功能生成的检查清单，用于测试规格说明而非软件。

客观上可判定的规则不应再只是请求：写入前钩子可以让 contracts/ 冻结成为强制措施，而 constitution.md 可以派生为工具自动读取的 AGENTS.md。参见 references/enforcement.md，其中也说明了哪些内容不应机械化。

每个阶段一条规则和一项禁令

阶段	规则	绝不允许
1 — 规格说明	每条 [MUST] 验收标准都能独立测试	实现细节——不提技术、函数或表名
2 — 规划	每条 [MUST] 验收标准至少对应一个组件	没有验收标准依据的抽象；constitution.md 之外的技术
3 — 任务拆分	每项任务都声明其满足的验收标准，先写测试	涉及约 3 个以上文件，或没有验收标准引用的任务
4 — 实现	每项任务使用一个全新上下文——完整加载 constitution.md，再加上仅与该任务相关的验收标准、契约、计划部分和实体	修改 contracts/、添加 spec.md 之外的行为、在任务间沿用上下文
5 — 验证	先修复代码以符合规格说明，再生成演练	修改规格说明以符合代码

阶段 1 — 规范定义

在生成 spec.md 之前运行 Assumptions Surface Prompt，这样角色、权限、错误处理和范围方面的隐含假设就能在固化为验收标准之前得到修正。如果 research.md 存在，规范不得与其矛盾。

spec.md 包含：概述、用户故事、边界（始终执行 / 先询问 / 绝不执行）、采用 Given/When/Then 格式并标注 [MUST] [SHOULD] [COULD] [WONT] 的验收标准、明确的范围外事项，以及待解决的问题。必须包含错误和边界情况的验收标准——只有理想路径永远无法通过 Gate 1。

完整规范或增量规范。 修改已有行为时，无需重新规范定义。增量规范先声明基线，再仅列出变更内容：

模式	适用情况	标题
完整	新能力，且没有需要保留的现有行为	Mode: Full
增量	更改、扩展或移除已发布的现有行为	Mode: Delta + Baseline:

增量规范中的验收标准标注为 [ADDED]、[MODIFIED]、[REMOVED] 或 [UNCHANGED]——最后一种用于标明变更不得破坏的行为。基线可以是先前的规范；如果没有，则使用 research.md 中引用的发现。缺少可明确解析的基线的增量规范无法评审——参见 references/workflow-phases.md → Delta Specs。

Gate 2 通过时，contracts/ 即予以冻结。逐步详述见 references/workflow-phases.md；提示词格式（A 适用于可访问文件的 Agent，B 适用于无状态接口）见 references/prompt-patterns.md；追溯矩阵、偏差报告和演练的格式见 references/output-formats.md。

---

规范偏差

当 AI 做出从未明确规定的“合理假设”时，就会产生偏差。上述每条规则都旨在消除一类假设：章程消除项目级假设，研究消除对现有系统的假设，澄清在歧义演变为架构之前消除歧义，冻结的契约消除接口猜测，每项任务使用单一上下文则消除从先前工作继承的假设。

还有两个习惯能解决其余问题：明确胜过冗长——“资源不存在时返回 404”胜过三段解释；以及每项任务完成后都提交，这样偏差总能通过一次还原来消除。

失败模式详见：references/anti-patterns.md。

---

上下文才是真正的限制

AI Agent 是无状态函数：输出质量受输入质量限制。这里的每个阶段、关卡和产物，本质上都是对哪些内容进入输入的机制化决策。

• 每个阶段产物都是一次压缩。 阅读四十个文件后留下的内容汇总为 research.md；研究结果中保留下来的内容汇总为 plan.md。每次压缩大约减少 95%，同时保留每项对决策至关重要的事实。因此，产物长度是质量信号——900 行的规范已不再是压缩，而是在囤积内容。
• 有意压缩，而不是等超限再压缩。 将利用率保持在 40–60% 区间。因耗尽而触发的自动压缩会在压力之下替你决定丢弃哪些细节。

完整模型：references/ai-agent-patterns.md → Context Engineering。

---

理解债务

规范能防范一种与正确性无关的失败模式：代码能正常运行，却无人理解。Agent 生成代码的速度比人类阅读快数倍，因此团队合并的拉取请求显著增多，对所发布内容的理解却有可衡量的下降。这笔债务在首次事故、入职培训或重构发生前不会造成任何成本。

只有实际阅读这些产物，SDD 才能偿还这笔债务。评审规范和计划，而不是略读差异——这样就能把注意力集中在约 400 行高密度内容上，而不是约 2000 行低密度内容上。将规范保留在同一个 PR 中，让评审者先读意图，再看实现机制；在阶段 4 后要求进行线性演练；归档规范而非删除，以便后来者能继承其中的推理过程。

Gate C 会在合并前强制执行这一要求。

---

与用户沟通

此工作流会生成大量 Markdown，其中大部分是供下一阶段使用，而不是给人看的。混淆两者，正是 SDD 获得繁文缛节之名的原因。

• 将产物写入文件。向用户展示结论。 刚写入磁盘的完整产物，绝不要直接粘贴到回复中。
• 先给结论，再给依据。 门禁结果、偏差报告和验证输出都要先给出通过／失败状态和数量，然后再提供细节。
• 用二元方式标明不确定性。 经代码或引用的产物核实后标记为 [CONFIRMED]，根据推断得出的标记为 [VERIFY]。绝不要编造置信度百分比。
• 遵守篇幅限制。 references/output-formats.md 中的每种面向用户的输出都有篇幅限制和格式要求。

---

持续维护文档

• 决策变更时： 运行 /sdd:amend——绝不要手动修改文件
• 代码在工作流之外发生变更时： 运行 /sdd:reconcile
• 让规范与代码一同提交： 规范文件应与实现放在同一个 PR 中
• 为规范标注版本： 每个 spec.md 都要包含 Status 和 Version 标头
• 完成后归档： 功能发布后，将已完成的规范移至 specs/archive/

规范与代码不一致的三种情况

混淆这些情况，会让规范悄然沦为虚构。对应的命令不同，修改的一方也不同：

情况	原因	命令	变更内容
偏差	实现意外偏离已批准的规范	/sdd:validate	代码
修订	需求确实发生变化	/sdd:amend	规范链，然后是代码
协调	有意在工作流之外变更代码——热修复、上游重构或其他团队的修改	/sdd:reconcile	由人工逐项差异决定

/sdd:reconcile 不会自行修改任何内容：它会对每项差异进行分类并提出处理方向，由人工逐项批准。自动接受其提议，会让它变成掩盖偏差的机器——参见 references/anti-patterns.md → Anti-Pattern 21。

---

参考索引

所有参考文件都位于当前目录下一层。只加载当前阶段所需的内容。

需求	文件
所有产物的模板	references/artifact-templates.md
各阶段交互提示词	references/prompt-patterns.md
按阶段详细说明	references/workflow-phases.md
评审清单、按领域生成的清单、CI/CD	references/quality-gates.md
钩子、契约锁、工作树、AGENTS.md 桥接	references/enforcement.md
所有用户可见内容的格式	references/output-formats.md
上下文工程和多 Agent 模式	references/ai-agent-patterns.md
常见故障模式与修复方法	references/anti-patterns.md
一页速查表	references/quick-reference.md
主题导航	references/INDEX.md