规范驱动开发 SDD：Specify→Plan→Implement→Validate 全流程

AI 写飞了，多半是因为一开始就没说清要做什么。

这句话不是在批评 AI——是在说工作流的问题。你跟 AI 说"帮我做一个用户管理模块"，它动手了，写了一堆代码，跑起来能跑，但权限逻辑跟你想的不一样，字段名不是你们团队的风格，测试也没有。于是你开始解释，它开始修，修了三轮还没到位，最终你自己手动改。

这个过程能省掉——如果你在开始之前就把"要做什么、做成什么样"写清楚。

这就是 SDD（Spec-Driven Development，规范驱动开发）的出发点。

---

SDD 是什么，为什么 AI 时代更需要它

SDD 不是什么新词，也不是某个特定工具或框架的专属概念。它的核心思路很朴素：先把你要做的事情写成一份规范（spec），再让执行者（人或 AI）按照规范干，最后对着规范验收。

在传统开发里，这套流程叫"先写需求文档再开发"，很多团队觉得麻烦就省掉了，靠口头沟通和"大家都懂"来对齐。小团队有时候能跑，因为人和人可以反复沟通、靠眼神确认意图。

AI 改变了这个假设。

AI 没有眼神，没有"懂行"的直觉，也不会因为觉得你想要 A 就猜到你真正要的是 B。它只能靠你给的文字来理解任务。你给的信息越模糊，它填空的自由度就越大，跑偏的概率就越高。

反过来说——如果你能把需求写得足够清楚、可验证，AI 执行得其实比人要稳定：不会因为心情不好就敷衍，不会因为赶时间就省步骤，每次都老老实实按规范来。

SDD 就是把这个"写清楚"的步骤系统化、可复用化，分成四步：Specify（写规范）→ Plan（拆计划）→ Implement（按计划实现）→ Validate（对照规范验收）。

和 Plan 模式 的关系：Plan 是 SDD 四步里的第二步，是其中一个环节。SDD 是更完整的工程框架，Plan 模式是 Claude Code 实现这个框架的一个具体功能。

---

四步全流程

第一步：Specify——写清楚你要什么

这一步的目的是把"我大概想要 X 功能"变成一份可以给 AI 看、也可以给自己审的书面规范。

该产出什么：一份 spec 文档（Markdown 就够），包含：

• 目标：这个功能/模块是干什么的，解决什么问题
• 输入输出：接口的入参和出参，或者 UI 的交互描述
• 验收标准：写成可测试的语句，比如"当用户输入空字符串时返回 400 错误"，而不是"做好参数校验"
• 不做什么：明确排除掉容易被 AI 过度发挥的方向

怎么让 AI 参与：你不必一个人从零写 spec。可以先给 AI 一段粗糙的描述，让它帮你起草，然后你修改补充：

我要做一个 CSV 文件上传功能，支持用户上传销售数据，系统解析后存进数据库。
帮我写一份简短的 spec，包含：功能目标、接口定义（入参/出参）、验收标准（至少 5 条）、明确不包含哪些功能。

AI 给的草稿不会完全准确——因为很多业务细节只有你知道。但它能帮你快速建起骨架，省掉"对着空白文档发呆"的时间。你的任务是补充细节、纠正误解、加上 AI 漏掉的约束。

写好 spec 之后，在交给 AI 执行前，自己先读一遍：如果有任何地方"我懂但没写出来"，补进去。那些你以为 AI 会猜到的东西，它不会猜。

---

第二步：Plan——把规范拆成实现步骤

有了 spec，下一步是把它拆解成具体可执行的步骤——这就是 Plan。

该产出什么：一份实现计划，把工作拆成若干小任务，每个任务有明确的产出（文件/函数/接口）。粒度建议：单个任务 AI 一次就能完成，不需要反复追加上下文。

怎么让 AI 参与：用 Claude Code 的 Plan 模式 或者直接在对话里：

这是我的 spec（粘贴 spec 内容）。
现在帮我做一个实现计划，拆分成具体步骤，每步说明：做什么、改哪些文件、完成标志是什么。

关键习惯：拿到计划后，你要审。看每个步骤是否和你的 spec 对应，是否有遗漏，步骤顺序是否合理（比如先建数据模型再做接口，不能反过来）。Plan 阶段发现问题的代价远小于 Implement 阶段发现——改一行计划文字，总比改半个模块的代码容易。

---

第三步：Implement——按计划实现

这一步是真正动代码的环节，但有了前两步，这里反而是风险最低的。

该产出什么：按计划完成的代码，每个步骤结束后有可验证的产出。

怎么让 AI 参与：逐步骤喂给 AI，每次给它当前步骤 + 相关 spec 片段 + 已有代码上下文：

按照我们的计划，现在做第 2 步：实现 CSV 解析模块。
spec 里的相关验收标准是：（粘贴相关部分）。
已有的数据模型见（附上代码）。

不要把整个计划一次性丢给 AI，让它自己一口气做完。一口气做完的代码你很难逐步审，遇到问题也难以定位是哪步出的错。分步来：做一步，看一步，确认再继续。

这里有个常见陷阱：AI 在执行时可能发现 spec 里有模糊的地方，它会自己做个假设然后继续。好的做法是让它遇到不确定的地方先停下来问你，而不是自己填坑：

如果在实现过程中发现 spec 里有歧义或者缺少信息，先暂停问我，不要自己猜。

这条指令值得每次 Implement 阶段都带上。

关于上下文管理：长任务跑下来上下文会越来越长，AI 的注意力会漂移。合理的拆分粒度加上 上下文窗口管理，能让每步实现质量更稳定。

---

第四步：Validate——对照规范验收

实现完了不等于做完了。Validate 是把你在 Specify 里写的验收标准逐条过一遍，确认代码真的满足了当初的要求。

该产出什么：验收报告（可以很简单，就是逐条打勾/打叉）+ 回归修复记录。

怎么让 AI 参与：

• 让 AI 对照 spec 的验收标准写测试用例（如果之前没写）：

  这是 spec 里的验收标准（粘贴）。帮我写对应的测试，覆盖每一条。
  

• 跑完测试后，如果有失败，让 AI 分析是代码问题还是 spec 写得有歧义，然后针对性修复。
• 让 AI 做一次"对照 spec 的 code review"：

  这是最终代码（附上），这是原始 spec（附上）。
  帮我逐条检查，有没有哪条验收标准在代码里没有覆盖到，或者实现和要求有偏差。
  

Validate 阶段的意义不只是"测试通过"，而是确认你当初写的那份规范确实得到了落实——这是整个 SDD 流程闭环的关键。如果 Validate 发现了遗漏，回头修，再验收，直到对齐。

---

一个小例子走完四步

场景：给一个 Express 应用加一个"用户标签"接口，支持给用户打标签、查标签。

Step 1：Specify

写出 spec（核心部分）：

• 目标：用户打标签，一个用户可以有多个标签，标签是字符串
• 接口：POST /users/:id/tags 接收 { tags: string[] }，返回更新后的用户标签列表；GET /users/:id/tags 返回用户当前标签列表
• 验收标准：
  • ✦ 打标签时如果用户不存在，返回 404
  • ✦ 标签列表为空数组时不报错，返回空数组
  • ✦ 打标签会覆盖已有标签，不是追加
  • ✦ 标签字符串最长 20 字符，超过返回 400
  • ✦ 单次最多 10 个标签，超过返回 400
• 不做：不做标签去重（由调用方保证），不做标签分类

Step 2：Plan

AI 拆出的计划（经你审核后）：

1. 在数据模型里给 User 加 tags: string[] 字段（默认空数组）
2. 实现 POST /users/:id/tags 路由和控制器，含参数校验
3. 实现 GET /users/:id/tags 路由和控制器
4. 写集成测试，覆盖 spec 里的 5 条验收标准

Step 3：Implement

按步骤逐一喂给 AI 执行，每步附上相关 spec 片段和已有代码。比如第 2 步：

按计划做第 2 步：POST /users/:id/tags 路由。
相关 spec：用户不存在返回 404；tags 数组最长 10 个、每个标签最长 20 字符超出返回 400；打标签覆盖已有标签。

Step 4：Validate

跑测试，所有 5 条验收标准都有对应用例且通过。让 AI 对照 spec 做一次代码审查，确认"覆盖而非追加"的逻辑在代码里是明确实现的，而不是"大概是这样"。

---

什么规模的项目值得上 SDD

SDD 不是万能药，也不是每个改动都要走全套流程。判断标准：

不必上 SDD：

• 改一个小 bug，范围清晰，改完自测一下就行
• 一两行的配置修改
• 写个一次性脚本，不进生产，用完即弃

应该上 SDD：

• 新建一个模块/服务，有多个接口或功能点
• 改动会影响其他人用的公共接口或数据结构
• 需要多轮 AI 协作完成，中途可能换人或换 session
• 需要向团队或产品解释清楚"做了什么、验收标准是什么"

判断原则：如果你解释"做了什么"需要超过两句话，或者验收需要靠记忆而不是文档，就值得写 spec。

关于 CLAUDE.md 和跨工具配置规范：SDD 的 spec 文档和 CLAUDE.md 是互补的——CLAUDE.md 放项目级约定（编码风格、命名规范、禁用模式），spec 文档放任务级要求（这次要做什么、验收标准）。两者配合，能给 AI 最清晰的上下文。

也可以去 Claude Code 工具页 看看 Plan 模式的具体操作方式，那是 SDD 里 Plan 步骤的最直接工具支撑。

---

故障排查表

症状	原因	解法
AI 实现结果和预期不一样，改了三轮还没对	Specify 阶段验收标准写得太模糊，或者漏了关键约束	回到 spec 补充"不做什么"和边界条件，尤其是那些你以为 AI 会猜到的地方
Plan 拆出来的步骤太大，一步做完 AI 生成代码量很多但质量不稳定	任务粒度太粗，超出 AI 单次可靠处理的范围	把大步骤再拆，每步最好对应单个函数或单个文件，控制输入输出范围
Validate 阶段发现漏了一个验收场景，不知道该改 spec 还是改代码	spec 和代码双向都可能有问题，需要判断哪个是"正确的"	先确认这个场景在业务上是否应该覆盖；如果是，补进 spec 再补实现；如果是 AI 自己加的逻辑跑偏了，删代码回归 spec
多 session 协作时，后来的 AI 不了解前面做了什么，乱改	没有把 spec 和 plan 作为持久化上下文传递	每次新 session 开头先附上 spec 文档和当前进度，而不是口头描述"上次做到哪了"
AI 在 Implement 阶段遇到歧义自己假设然后继续，最后发现假设错了	没有在指令里要求遇到不确定先停下来问	每次 Implement 阶段在提示里加上"遇到 spec 里没说清楚的地方先停下来问我，不要自己猜"

---

常见问题

Q：SDD 和 TDD（测试驱动开发）有什么区别？

TDD 是先写测试再写代码；SDD 是先写规范再写代码（测试是验收规范的一种方式，但不是 SDD 的必要步骤）。两者可以结合：在 Specify 阶段直接把验收标准写成可运行的测试，这样 Validate 阶段就是跑测试是否全绿。

Q：spec 要写多细才够用？

够细的标准是：把 spec 直接给一个没有背景的 AI，它能理解任务边界、知道什么算完成、知道什么不该做。如果你发现自己在对话里不断补充"还有一个条件是……"，说明 spec 不够细。

Q：Plan 那步 AI 拆出来的步骤顺序不对，我能改吗？

应该改。Plan 是给你审的，不是直接执行的。AI 不了解你项目里的具体依赖关系或者团队约定，步骤顺序、粒度、命名都可能需要你调整。调整之后再拿去 Implement。

Q：小改动也要写 spec 吗，感觉太重了

不必。SDD 是工具，不是仪式。一句话能说清楚的改动，直接告诉 AI 做就行。SDD 的意义在于当任务复杂到靠口头说不清楚的时候，给你一个系统化的方法把"说清楚"这件事做完。

Q：spec 文档放哪里合适？

可以放在项目的 docs/ 目录，用 Markdown 管理，和代码一起进 git。这样历史可查，也方便在新 session 里直接引用文件路径而不是粘贴全文。

---

👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。