规约驱动开发（SDD）——让规约成为人与 AI 之间的“合同“

核心论点：AI 编码最大的不确定性来自需求模糊。规约驱动开发（Spec-Driven Development）把需求变成一份结构化的"合同"——AI 拿着这份合同写代码，写完后再对照合同自检。整个流程从"你猜我要什么"变成"你按我的规约交付"。

为什么 SDD 对 AI 编码特别重要

对比三种信息传递的精确度：

规约 = 消除 AI 的"自由发挥空间"。模糊是 AI 的天敌——你越模糊，AI 填补的假设越多，返工越多。

SDD 规约的三层结构

基于项目的规约约定，一个完整的规约包含三层文档：

.codebuddy/specs/退款确认功能/ ├── 需求规格说明书.md ← 做什么（功能边界） ├── 开发任务计划.md ← 怎么做（拆解到可执行单元） └── 项目总结报告.md ← 做得怎么样（验收结果）

第一层：需求规格说明书——AI 帮你穷举边界

不要让 AI 凭空写规约。给它一个用户故事，让它展开：

输入（人写）： "用户在订单详情页发起退款申请，小额（≤100元）自动退款， 大额需人工审核，审核通过后原路退回。" 让 AI 展开以下维度： 1. 功能范围（含什么 / 不含什么） 2. 前置条件（用户必须有已完成订单） 3. 主流程（一步一步） 4. 异常分支（至少列 5 种：订单不存在、已退款过、支付方式不支持原路退回…） 5. 非功能需求（响应时间、并发量、数据一致性要求） 6. 验收标准（可测试的 checklist）

AI 的输出不再是猜测，而是你能逐条审核的规约。你不满意的地方，改规约，不改代码。

第二层：开发任务计划——AI 拆解规约

规约写好后，让 AI 从规约中拆解任务：

请基于《需求规格说明书》拆解开发任务。 要求： - 每个任务可独立完成，时间 ≤ 4 小时 - 标注任务依赖关系 - 标注哪些任务适合 AI 完成，哪些需要人决策 - 输出格式：`[ID] [依赖] [耗时] [负责人/AI] 任务描述`

输出示例：

## 开发任务计划 ### 基础设施 - [T1] [无] [2h] [AI] 新增 refund 数据库表（refund_records + refund_logs） - [T2] [T1] [1h] [AI] 新增 RefundRepository 数据访问层 ### 核心逻辑 - [T3] [T2] [4h] [AI] 实现 RefundCoordinator（自动审批 + 人工审批路由） - [T4] [T3] [3h] [AI] 实现原路退回适配器（微信/支付宝/银行卡） ### 集成 - [T5] [T4] [2h] [AI] Orchestrator 路由集成（refund 意图 → RefundCoordinator） - [T6] [T5] [2h] [AI] 退款结果回写对话上下文 ### 测试 - [T7] [T6] [4h] [AI→人审] 单元测试 + 集成测试 + 异常路径覆盖

第三层：项目总结报告——AI 对照规约验收

开发完成后，让 AI 逐条对照规约生成验收报告：

请对照《需求规格说明书》的验收标准，逐条检查代码实现： [✓] AC-1：小额退款（≤100元）自动审批，3 秒内完成 → RefundCoordinator.auto_approve() [✓] AC-2：大额退款进入人工审核队列 → RefundCoordinator.enqueue_manual_review() [✗] AC-3：审核超时 24 小时自动提醒 → 未实现，需补充定时任务 [✓] AC-4：退款失败自动重试 3 次 → retry_decorator(max_attempts=3) ...

这份报告就是项目总结报告.md——不是事后补写的文档，而是开发过程中自然沉淀的产物。

SDD 的核心原则

规约先于代码，不可逾越

❌ "先写着，规约后面补" → AI 在猜测中工作，返工率 40%+ ✅ 规约至少覆盖以下内容再开始编码： - 主流程 + 2 条异常分支 - 验收标准 3 条 - 非功能需求 1 条

不需要规约完美。规约的价值在于"有"，不在"全"。

规约是活文档，与代码同步演进

发现规约遗漏 → 先改规约 → 再改代码 不是： 发现规约遗漏 → 直接改代码 → 规约变成废纸

这要求规约和代码放在同一个仓库——这正是.codebuddy/specs/的设计意图。

AI 写规约，人审规约

AI 擅长穷举——它能列出 20 种异常分支。但只有人知道哪些业务分支是真实存在的，哪些是过度设计。人的审查触点是规约，不是代码。

SDD 在 Agent 流水线中的位置

SDD 走在所有 Agent 之前，为整个流水线提供"方向盘"：

用户需求 ↓ 需求规格说明书 ← AI 展开 + 人审核（SDD 的核心） ↓ 开发任务计划 ← AI 拆解 ↓ architecture-designer ← 以规约为输入，不凭空设计 ↓ coder ← 以规约 + 架构设计为输入 ↓ test-generator ← 以验收标准为测试用例来源 ↓ code-reviewer ← 以规约中的非功能需求为审查标准 ↓ 项目总结报告 ← AI 逐条验收

规约是整个流程的"单一真相来源"。当架构设计和需求冲突时——改架构。当测试和需求冲突时——改测试。只有需求本身的变更需要人确认。

最小可行 SDD——从今天就能开始的实践

不要等"完美的规约模板"。从最小版本开始：

第一天：写一个 10 行的规约

## 功能：XXX 1. 主流程：A → B → C 2. 异常情况：（至少列 3 个） 3. 验收标准：（至少 3 条可测试的）

第一周：把规约喂给 AI

@.codebuddy/specs/XXX/需求规格说明书.md 请实现这个功能

对比一下：和你不给规约直接让 AI 写代码，返工轮数差多少？

第一个月：建立 SDD 习惯

• 每个新功能先在.codebuddy/specs/下建目录
• 规约写好后丢给 AI 展开 → 人审 → 定稿
• 代码写完后 AI 逐条验收

SDD 解决的是 AI 编码中最根本的问题：你无法责怪 AI 不理解你的需求，如果你没有写下来。规约就是那份写下来的"合同"——AI 照着合同交付，你照着合同验收。模糊消失了，返工也就消失了。