核心论点AI 编码最大的不确定性来自需求模糊。规约驱动开发Spec-Driven Development把需求变成一份结构化的合同——AI 拿着这份合同写代码写完后再对照合同自检。整个流程从你猜我要什么变成你按我的规约交付。为什么 SDD 对 AI 编码特别重要对比三种信息传递的精确度方式指令示例AI 理解偏差率典型问题口头描述“加个退款功能”高AI 会假设退款流程、金额限制、通知方式——全凭猜测自然语言需求“用户申请退款 → 管理员审核 → 原路退回”中边界情况未覆盖审核超时金额不对失败重试结构化规约规约文档前置条件、主流程、异常分支、验收标准低AI 有明确的对错标准不再猜测规约 消除 AI 的自由发挥空间。模糊是 AI 的天敌——你越模糊AI 填补的假设越多返工越多。SDD 规约的三层结构基于项目的规约约定一个完整的规约包含三层文档.codebuddy/specs/退款确认功能/ ├── 需求规格说明书.md ← 做什么功能边界 ├── 开发任务计划.md ← 怎么做拆解到可执行单元 └── 项目总结报告.md ← 做得怎么样验收结果第一层需求规格说明书——AI 帮你穷举边界不要让 AI 凭空写规约。给它一个用户故事让它展开输入人写 用户在订单详情页发起退款申请小额≤100元自动退款 大额需人工审核审核通过后原路退回。 让 AI 展开以下维度 1. 功能范围含什么 / 不含什么 2. 前置条件用户必须有已完成订单 3. 主流程一步一步 4. 异常分支至少列 5 种订单不存在、已退款过、支付方式不支持原路退回… 5. 非功能需求响应时间、并发量、数据一致性要求 6. 验收标准可测试的 checklistAI 的输出不再是猜测而是你能逐条审核的规约。你不满意的地方改规约不改代码。第二层开发任务计划——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_attempts3) ...这份报告就是项目总结报告.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 照着合同交付你照着合同验收。模糊消失了返工也就消失了。
