1. 从“想到哪写到哪”到“先想清楚再动手”：SDD 解决的真实痛点
我最早接触 SDD（Specification-Driven Development，规格驱动开发）并不是因为它时髦，而是被逼的。当时团队在做一个人工智能辅助专利检索的系统，代码写了大概两万行，结果产品经理一句话“检索结果的排序逻辑不对”，我盯着满屏的 if-else 看了整整一个下午，愣是没敢动手改。那种感觉就像你在一团乱麻里找线头，每一根都像是真的，但拉一下就会打一个死结。
后来我开始尝试把“开发前先写清楚要做什么、怎么判断做对了”这件事当成第一优先级，才发现这其实正是 SDD 的核心思想。简单说，SDD 不是让你多写文档，而是让你在动手写代码之前，先把“需求是什么、系统应该怎么表现、边界在哪里、怎么验证”这些事用结构化的方式写清楚。它和我们常说的 TDD（测试驱动开发）不一样，TDD 关注的是“代码层面的行为验证”，SDD 关注的是“整个系统层面的规格定义”。
用一句大白话总结：TDD 是让你先写测试再写代码，SDD 是让你先写清楚“这玩意儿到底是干嘛的”再碰键盘。
真正让我下定决心系统梳理 SDD 方法论的文章，是 Thoughtworks 杰出工程师 Birgitta Böckeler 提出的一套三级分类框架。她把 SDD 分成三个层级，这个框架对我的启发很大。她说 SDD 不是一种单一的做法，而是三种不同粒度的实践的组合：
- 第一级：Specification by Example（面向示例的规格）—— 用具体的输入输出例子来描述需求，相当于给需求“拍照片”；
- 第二级：Executable Specification（可执行的规格）—— 把规格文档变成计算机能理解的断言或测试，相当于给需求“做体检”；
- 第三级：Living Documentation（鲜活的文档）—— 让文档和代码同源，实现“文档即代码”，相当于给项目“装监控”。
这三个层级不是互斥的，你完全可以根据项目的实际情况混用。但我个人的经验是，哪怕只做到第一级，也就是把“示例化需求”这件事做扎实，收益也已经非常可观了。这套方法论适用于几乎所有软件项目——无论是个人项目、初创团队、还是大型企业里的复杂系统，只是实施的深度和形式不一样。
下文我会用自己完整实践过的一个项目作为例子，一步步拆解 SDD 的完整落地过程，包括需求拆解、规格撰写、验证设计、AI 辅助编程的协作方式，以及过程中踩过的所有坑。这篇内容既是给想入门 SDD 的朋友的路线图，也是给我自己的复盘笔记。
2. 需求拆解：用“三级分类”把模糊想法变成可执行规格
2.1 从一个模糊的项目需求开始
先交代一下项目背景。当时我们接到一个内部工具的开发需求：做一个“AI 辅助生成项目周报”的系统。需求描述非常模糊：输入一段本周工作流水账，让大模型帮忙生成一份结构化的周报，并且能区分“本周完成”“下周计划”“风险与求助”几个板块。
这种需求听起来简单，但真的做起来你会发现到处都是坑。比如：
- 什么叫做“结构化”的周报？是固定模板还是自由格式？
- 大模型输出的内容要不要保证百分百准确？如果它编造了一个根本不存在的工作项怎么办？
- 用户输入的是口语化的流水账，是否需要先做意图识别或者实体抽取？
- 周报生成完之后，需不需要支持人工编辑？编辑后的内容要不要回流给模型做二次训练？
如果直接撸起袖子开始写代码，我大概率会做出一个表面上能“生成周报”但处处难用的半成品。有了 SDD 的框架之后，我的第一步就变成了写文档。
2.2 第一级：用“面向示例的规格”敲定需求细节
我做的第一件事，是和产品经理、还有两个核心用户（开发团队里的技术组长和运营同学）坐在一起，让他们各自给出 3 到 5 个他们心目中“理想周报”的输入输出示例。
比如我们收集到的其中一组输入是：
输入：这周主要做了三件事：第一，修复了登录模块的 session 失效 bug，用户反馈很多；第二，和设计同学对了一下新版首页的交互稿，基本定了；第三，帮忙 review 了同事的订单导出功能 PR。另外下周要开始做支付模块的重构，风险是第三方支付回调经常超时。对应的理想输出是：
【本周完成】 1. 修复登录模块 Session 失效问题，解决了大量用户反馈，提升系统稳定性。 2. 完成新版首页交互方案评审，与设计团队达成一致，确定最终方案。 3. 参与订单导出功能代码评审，保证代码质量。 【下周计划】 启动支付模块重构，制定详细实施方案。 【风险与求助】 第三方支付回调存在超时现象，可能影响重构进度，需协调后端及运维资源联合排查。我总共收集了大概 15 组类似的输入输出示例，然后把它们打印出来贴在白板上。注意，这一步非常关键。在做任何技术方案之前，先用示例把需求锚定住，这样才能避免后续开发中“搞出来的东西不是用户想要的”这种大坑。
2.3 第二级：把示例转化成可执行的验证标准
有了示例之后，就把它们写成可验证的测试用例。不是说非要马上写代码自动化测试，可以先写成表格。比如这样的测试用例表：
| 编号 | 输入特征 | 期望输出特征 | 验证方式 |
|---|---|---|---|
| TC-01 | 输入包含“修复了 bug” | 输出归类到“本周完成”且包含“修复”语义 | 检查输出结构/关键词 |
| TC-02 | 输入包含“下周要开始”或“计划” | 输出归类到“下周计划” | 检查输出结构/关键词 |
| TC-03 | 输入包含“风险”“阻塞”“超时” | 输出归类到“风险与求助” | 检查输出结构/关键词 |
| TC-04 | 输入包含多条不同类别的事项 | 输出按类别分组且不重不漏 | 检查输出的分组结果 |
这些用例看起来很简单，但它们其实是在定义需求的最小验收标准。有了这套标准，后续开发就变成了“让程序通过这些测试用例”，而不是“让程序员猜需求”。
2.4 第三级：让文档、代码和验证一体化
第三级是最理想的状态，也是最难一步到位的。我当时的做法是折中的：先把需求和测试用例写进一个 Markdown 文件（叫 requirement.md），再在代码注释里引用这个文件的章节。后续当代码变动导致测试用例失效时，我会强制要求自己同步更新 requirement.md。
这就形成了文档和代码的联动。虽然没有做到“文档即代码”那种极致状态，但至少不会出现“代码已经改了好几版，文档还停留在当初”的情况。
提示：对于小团队和个人项目，第三级不必追求“自动化生成文档”这种重武器。用 Git 提交信息绑定需求文档的变更记录，性价比最高。
3. 规格落地的关键技术选择：提示词设计、模型选型与结构化输出
3.1 为什么不能用“最贵的模型”一劳永逸？
需求定义了之后，最核心的技术决策来了：选什么大模型，怎么设计提示词，怎么处理模型的输出。
很多人第一反应是“直接调 GPT-4o 或者 Claude 的最强模型，把需求文本塞进去，让它生成周报”。但实测下来直接这么干有几个问题：
- 成本高：团队内每天可能有上百人使用周报生成功能，每次都调用最强模型，费用非常吓人；
- 延迟高：最强模型响应时间通常要 3 到 5 秒，对于“生成周报”这种高频操作太慢了；
- 输出不稳定：大模型的自由发挥会让同样的输入在多次调用后产生完全不同格式的周报，很难做后续的自动化处理。
所以我最后的方案是：用中等能力的模型（比如 GPT-4o-mini 或 Claude Haiku 级别）配合强约束的提示词，并且要求模型输出严格的 JSON 结构。
3.2 结构化输出的提示词设计
为了让模型输出稳定的 JSON，我在提示词里做了三件事。第一，给出明确的输出 Schema 定义；第二，给出少样本示例（few-shot examples）；第三，在提示词里加入“思维链”约束，让模型先思考分类再生成内容。
我最终的提示词模板大致长这样（有删减）：
你是一个项目周报生成助手。请根据用户输入的流水账，生成结构化周报。 输出必须使用以下 JSON 格式，不要输出任何其他内容： { "completed": ["事项1", "事项2"], "nextWeek": ["事项1"], "risks": ["风险描述"] } 分类规则： - 表示已经完成的工作，放到 completed。 - 表示未来计划、下一步行动，放到 nextWeek。 - 表示风险、阻塞、超时、资源不足等，放到 risks。 - 如果一条描述同时包含完成和风险，拆分成两个条目分别归入对应分类。 示例输入： 这周修了登录 bug，下周准备搞支付。 示例输出： {"completed": ["修复登录 bug"], "nextWeek": ["准备支付模块工作"], "risks": []} 现在请处理以下输入： {user_input}这里的关键是“不要输出任何其他内容”和明确的 JSON Schema。加上少样本示例之后，模型的输出基本能做到百分百可解析。实测下来，在 GPT-4o-mini 上 JSON 解析失败率低于 0.5%，完全可接受。
3.3 处理模型输出的边界情况的技巧
当然，模型总会有出意外的时候。我的处理方式是加了一层“下游容错”，在解析 JSON 时做三个策略：
- 如果 JSON 解析成功，直接使用；
- 如果解析失败，尝试用正则抽取
completed、nextWeek、risks里数组内容； - 如果还失败，直接返回“生成失败”让用户重新提交一次。
这里给一个 Python 解析函数的简化版本：
import json import re def parse_llm_response(response_text): """尝试解析 LLM 输出的 JSON，带降级策略""" # 策略 1：标准 JSON 解析 try: data = json.loads(response_text) if all(k in data for k in ("completed", "nextWeek", "risks")): return data except json.JSONDecodeError: pass # 策略 2：正则抽取 try: completed = re.findall(r'"completed":\s*\[(.*?)\]', response_text, re.S) next_week = re.findall(r'"nextWeek":\s*\[(.*?)\]', response_text, re.S) risks = re.findall(r'"risks":\s*\[(.*?)\]', response_text, re.S) if completed or next_week or risks: return { "completed": _extract_items(completed), "nextWeek": _extract_items(next_week), "risks": _extract_items(risks), } except Exception: pass raise ValueError("无法解析模型输出")注意：设计提示词时，不要写“请生成一份周报”这种太过开放的要求。凡是要程序自动处理的内容，都必须限定输出格式；凡是自由发挥的余地，都会变成后续解析和处理的成本。
4. 从“规格”到“代码”：AI 辅助开发中的角色重分配
4.1 有了规格，AI 编程才能发挥真正价值
跑题跑得有点远了，回到开发本身。为什么说 SDD 和 AI 编程是天作之合？因为 AI 编程的痛点从来不是“代码写不出来”，而是“代码写出来不符合要求”。
我以前做 AI 编程的时候，经常会有这种体验：让 AI 帮忙写一个接口，它写得又快又工整，但往往不是我想要的逻辑。问题出在哪？出在给 AI 的需求本身就不够具体。你如果说“帮我写一个函数把用户数据存进数据库”，AI 会给你一个最普通的实现。但如果你在规格里写清楚“用户数据包含 name、email、age 三个字段，email 格式必须校验，重复 email 返回 409 错误”，AI 就能给你一份几乎和需求完全对齐的代码。
SDD 本质上是在给 AI 编程“投喂高质量的上下文”。规格文档写得越清晰，AI 生成的代码越精准。这也是很多人说的“vibe coding 到 harness × SDD 全栈开发实战”的核心思路：用规范约束 AI 的发挥，而不是让 AI 随性挥洒。
我测试过一种工作流：把需求规格 Markdown 文件、当前项目代码结构说明、以及一个目标函数的详细描述，一起放进上下文里，然后让 AI 给出实现方案。这种方式生成出来的代码质量，通常比我口头描述需求让 AI 生成的代码高一个量级。核心变量就是规格的清晰度。
4.2 AI 在 SDD 不同阶段可以扮演的角色
顺着这个思路往下推，我开始把 SDD 六个步骤里的每一个环节都尝试引入 AI 辅助：
| 阶段 | AI 可以帮忙做的事 | 我的建议 |
|---|---|---|
| 需求收集 | 根据原始描述生成更多的输入输出示例 | 推荐，能大幅提高示例覆盖度 |
| 规格编写 | 把示例转化成 Gherkin 语法或测试用例表 | 推荐，但要人工校对语义 |
| 测试设计 | 根据规格生成边界测试用例 | 推荐，AI 很擅长发现边界情况 |
| 代码实现 | 根据规格直接生成目标代码 | 强烈推荐，这是 AI 最擅长的 |
| 验证审查 | 生成测试报告，检查当前实现和规格的差距 | 可用，但严格审查需人工 |
| 维护迭代 | 根据代码变更自动更新规格草稿 | 谨慎使用，防止规格失真 |
我自己实际偷偷用了一个小技巧：把测试用例表复制给 AI，让它给出“这些用例对应的代码实现”。AI 会逐条对照用例去写代码，覆盖率和准确率比我盲写要高很多。
4.3 关于“无限制 AI”类工具的技术选型建议
这里要特别提醒一下技术选型问题。有一些团队的开发人员在找 AI 辅助工具时很在意“无限制、不审核”这些卖点。但我强烈不建议在生产环境使用这类没有安全边界的工具，尤其是涉及企业内部数据、专利相关内容、或者用户隐私信息的时候。
工具选型的核心原则，是模型的输出质量和服务稳定性，以及数据合规性，而不是它有多“放得开”。我在实际工作中更推荐使用 OpenAI、Anthropic、百度文心、通义千问这类有明确数据使用政策的主流大模型服务。特别是涉及企业核心项目代码时，最好通过内部私有的 API 网关来调用，确保代码不会流入第三方训练集。
实操心得：如果你的项目包含专利、法务、金融等敏感领域，一定要在选型清单上增加“数据隔离”和“审计日志”两项硬性指标。不要因为一时方便用了一个来路不明的“无限制”服务，等出了事故再补救，代价太大了。
5. SDD 六步实践指南：从零到一的操作手册
5.1 我的六步落地流程
从第一个 SDD 项目到现在，我逐渐把整个流程沉淀成了固定的六个步骤。这套步骤也叫“SDD 六步实践指南”，其实核心思想非常简单，但如果你想直接套用，可以按照下面的顺序来执行。
第 1 步：澄清战略意图
先问清楚：我们为什么要做这个功能？它解决什么问题？为谁服务？优先级多高？这些内容不写进技术文档也行，但要在团队内部达成一致。在我周报生成器项目中，战略意图就是“减少开发团队每周花在写周报上的时间，目标是把平均耗时从 30 分钟降到 5 分钟以内”。
第 2 步：寻找锚定示例
收集 5 到 20 组真实输入输出示例。注意，这里的企业示例一定来自真实用户，而不是我们想象出来的。示例的价值在于“锚定”，它给整个团队提供了参考标准。
第 3 步：按模块拆分需求规格
不要试图一次写完整个系统规格。按模块拆：输入清洗模块、分类模块、周报生成模块、输出格式化模块。每个模块单独写一两页的规格描述，包含输入、输出、边界、异常处理。
第 4 步：建立可执行的验证基准
把示例转化成可运行的测试用例。如果项目允许，用 Cucumber 或 Pytest 写自动化；如果时间紧，至少用表格维护一份“测试用例清单”。
第 5 步：与 AI 结对实现
这一步是 AI 时代的特色。把规格、测试用例、项目结构说明放进 AI 编程工具的上下文，让 AI 生成初步实现，再人工审查和修改。审查的关键不是看代码风格，而是看实现是否“忠于规格”。
第 6 步：让文档成为“活文档”
代码变更后，同步更新规格文档和测试用例。我个人的方式是，每次 commit 时在 commit message 里加上需求文档编号，比如feat: 支持风险识别 #REQ-003。后续做文档回溯就非常方便。
5.2 一个完整的规格文档骨架
为了让这套流程更可复制，我给出一个我在实际项目中使用的 Markdown 规格模板，可以直接拷贝改：
# 需求标识：REQ-003 ## 战略意图 （背景、痛点、目标） ## 功能范围 （输入描述、输出描述） ## 核心场景示例 ### 示例 1：常规周报生成 - 输入：... - 期望输出：... ### 示例 2：包含风险提示的周报 - 输入：... - 期望输出：... ## 边界条件 - 输入为空时如何处理？ - 输入超过 5000 字时如何处理？ - 模型不可用时的降级策略？ ## 验收标准 - Given 用户输入... When 调用生成接口 Then 返回... - Given 模型输出非法格式 When 调用解析器 Then 返回友好错误 ## 相关测试用例 - TC-01，TC-02...有了这个模板，即使团队里来了新同学，他也能在十分钟内对项目要做什么、做到什么程度算完成，有一个清晰精确的认知。
6. AI 时代的新角色边界：产品负责人、开发者与智能体的协作模型
6.1 人机协作中的角色定义
SDD 不只是“写写文档”这么简单，它还会深刻改变团队的协作模式。尤其是当 AI 智能体（AI Agent）开始参与代码生成之后，团队里每个人、每个工具的角色必须重新定义。
我个人总结了一个三角色协作模型：
- 产品负责人：负责第 1 步的战略意图和第 2 步的锚定示例。他输出的不是 PRD 文档，而是“需求示例集”。
- 开发者：负责把示例转化为规格（第 3 步），并且编写自动化验证用例（第 4 步）。在 AI 编程越来越强的背景下，开发者的核心产出不再是代码，而是“问题定义”和“验收标准”。
- AI 智能体：负责把规格翻译成具体实现（第 5 步），并主动发现规格中的矛盾或遗漏。比如，你给 AI 输入规格文档后，它可以反向提问：“如果用户输入同时包含完成事项和风险，需要拆分输出吗？”——这是 AI 在做需求澄清，而不是在写代码。
这种模型下，人不再是唯一的“需求翻译器”，AI 也不仅仅是“代码生成器”，两者成了互相校验的搭档。这也是我从“vibe coding”进化到“harness × SDD 全栈开发”的核心转变：vibe coding 是让 AI 带着感觉飞奔，harness 则是用 SDD 给 AI 装上方向盘和刹车。
6.2 一个真实协作场景的复盘
有一次，产品负责人给了一个新需求：“在周报生成器中增加对上周计划的回顾功能”。按照直觉，大家可能会直接改提示词，让模型在生成新周报之前先对比上一周的 nextWeek 列表，然后把完成情况标成“已完成/未完成”。
但用 SDD 的方法，我们先写了一个测试用例：
Given 上周周报中 nextWeek 包含“完成支付模块重构” When 用户生成本周周报，且输入中描述“支付模块重构完成” Then 周报的 completed 分组中，对应事项应标记为“已完成”，并自动关联上周计划结果这个测试用例一写出来，产品负责人自己就发现问题了：如果用户输入里根本没有提到“支付模块重构”，那程序是应该自动认为“未完成”，还是应该什么都不写？这个边界不定义清楚，AI 就会“自由发挥”，而不同用户得到的结果就可能完全不一样。
最后我们在规格里补了一条规则：“当上周计划事项未在本周输入中被明确提及且未出现在已完成列表中时，系统不自动输出‘未完成’，只在风险栏提示‘存在未明确的计划事项’。”
这个细节如果没有 SDD 流程，十有八九会被忽略。但正是因为这一条，让最终的用户体验稳定性提升了一个档次。
7. 文档不是负担，是 AI 时代开发者的核心杠杆
7.1 很多人对 SDD 的误解
我经常听到一种论调：“SDD 不就是写文档吗？太浪费时间了。”或者：“现在都 AI 编程了，AI 直接能写代码，要文档干嘛？”
说这些话的人，大概率没有真正在一个复杂项目里被需求反复变更逼疯过。实际上，文档不是写给人类看的，更是写给 AI 看的。在传统开发时代，写文档的收益可能要在几个月后需求变更时才体现出来；但在 AI 时代，一份精确的规格文档带来的收益是即时可见的——因为 AI 直接使用文档来生成代码、生成测试、生成部署配置，文档就是 AI 的“输入数据”。
从投资回报率来看，每花 1 小时写规格文档，至少能节省 3 到 5 小时的无效开发和返工时间。我自己在周报生成器项目里做过粗略统计：规格化的需求编写投入约 6 小时，但因为需求清晰带来的返工减少、测试效率提升，本来就预计要 2 周完成的项目，最终 5 个工作日就交付了，节省的时间非常可观。
7.2 我的个人体会与扩展方向
写到这里，SDD 从理论到实战的完整脉络已经分享完了。这半年多实践下来，我最深的体会是：SDD 不是一个“文档管理方法论”，而是一个“复杂度控制系统”。它把最大的复杂度从“写代码时”转移到了“写规格时”，而写代码恰恰是现在的 AI 最擅长的事情；写规格则是最需要人类经验、判断力和领域知识的事情——两者恰好形成了最优分工。
最后再分享一个小技巧：我在完成每个需求文档时，都会在结尾加一个“开放问题”区，把当时没有结论、需要继续探索的点全部列进去。这个区域不需要有答案，但它会在几周后帮我快速回忆起当时的思考脉络。这个方法让我在和 AI 协作时，永远知道哪些地方应该由我拍板，哪些地方可以放手让 AI 去试。如果你正在寻找一种让 AI 编程更可控、让需求更清晰、让团队协作更有章法的方式，SDD 值得你花一周时间认真试一次。
