SDD 实战手记 [02-10] - Code Is Cheap. Show Me Your Spec.

公众号名称：dolphin07

作者名称：Dolphin7

发布时间：2026-06-10 20:34

上周团队里一个核心开发跟我说：「我试了 OpenSpec，生成的 spec 我看不懂，不如我自己和 Claude 聊几轮，让它出一份详细的技术方案，然后按方案来写代码。SDD 到底有什么用？」

我想了想，发现他说的方式其实已经在做 SDD 了——只是他没意识到。

他和 AI 反复对话收敛出来的那份”详细技术方案”，本质上就是一份 Spec。区别在于：这份 Spec 留在了他一个人的聊天记录里，下次换个人做类似需求，得从头再来一遍。

SDD 不是”多写一份文档”，是把你已经在做的事情（反复 Prompt 收敛路径）的结果固化下来，让它可复用、可审核、可传递。

一、SDD 是什么——先看学术定义

官方定义

在软件工程中，Specification（规格说明） 有一个经典定义：

“A specification describes what the system should do but not how it should do it.”
— IEEE Std 830-1998 (Software Requirements Specification)

将这个定义代入 AI 时代的语境：

Spec-Driven Development（SDD）= 通过显式的、结构化的规格说明（Specification）将 Intent 到 Code 的非确定性映射，收敛为可审计、可验证的高确定性交付路径。

换句话说：SDD 要解决的核心问题是——在 Intent → Code 的组合级路径空间中，建立确定性的工程交付保障。

关键要素：

要素	含义
显式	写出来的、可版本控制的、可审查的——不是聊天窗口里的一次性对话
结构化	分层描述 What / How / Plan——方便人 Review、方便 AI 执行
高确定性	同一份 Spec → 不同人/不同模型执行 → 产出在约束边界内收敛（注意：Spec→Code 仍有损，不保证完全一致，但关键路径锁定）
可审计	每条约束有编号、有判据，出了问题可以追溯到决策源头

SDD 不是一个具体工具，是一种研发范式。OpenSpec、Superpowers、Plan Mode、Kiro 都是这个范式下的不同实现。

二、为什么需要 SDD——Intent → Code 的路径爆炸

核心矛盾：Intent → Code 无数条路径，只需要一条

每一个需求（Intent）到实现（Code）之间，存在指数级的路径可能：

Intent: "实现一个抓球扣费功能"
         │
         ├─ 先扣后抓？先抓后扣？
         ├─ 幂等用数据库唯一键？还是 Redis SET NX？
         ├─ 失败重试 3 次？5 次？不重试？
         ├─ 余额校验放网关？放 Service？放 Repository？
         ├─ 并发锁粒度：用户级？订单级？全局？
         └─ ……
         
路径数 = 决策点₁ × 决策点₂ × … × 决策点ₙ → 爆炸

实际工程需要的不是”某条能跑的路径”，而是确定性的、可审计的、团队共识的那一条。

三种编程范式，本质上是三种不同的”路径收敛策略”。

三代编程范式——各自怎么解决路径爆炸

古法编程——人脑逐行决策，收敛靠经验

工程师在写代码的过程中逐行做路径选择——靠脑中的隐性上下文（经验、偏好、团队规范）完成收敛。确定性高，但慢。 每条路径都是人用时间换来的。

Vibe Coding——AI 替你选路径，Code 成本降了一个量级

公平地说：Vibe Coding 比古法编程进步了。 Code 的生产成本从”小时”降到”秒”——这是质变。对于探索性工作、原型验证、脚本工具，Vibe Coding 是正确选择。

但它有一个结构性问题：路径选择变成了 AI 的随机采样。

Vibe Coding 的收敛困境

你第一次 Prompt 得到的代码大概率不完全对。于是你开始迭代：

Prompt v1 → 代码不对 → 补充约束 → Prompt v2 → 部分对了 → 再补 → v3 → …

这个反复沟通的过程，本质上就是在逐步收敛路径。但问题在于：

1. 收敛过程不可沉淀：你和 AI 对话了 15 轮才把路径定下来——但这 15 轮对话是一次性的。下次做类似需求，你得从头来。
2. 收敛结果不可复用：你好不容易通过反复 Prompt 把路径收敛了，但换一个人做同类需求，他得重新走一遍同样的试错。因为你的”收敛经验”留在了聊天记录里，不是可传递的资产。
3. 不同人收敛到不同路径：同一个 Intent，5 个人各自 Prompt，得到 5 种不同实现。团队协作时，这些不同路径在代码合并时才暴露冲突。
4. 无法审计收敛结果：代码出问题后，你无法回溯”AI 当时基于什么约束选了这条路径”。

Vibe Coding 的本质：用廉价的 Code 生成 + 昂贵的反复沟通来完成路径收敛。收敛成本从”写代码”转移到了”反复 Prompt”——但没有降低，只是换了个地方花。

从 Vibe Coding 到 SDD——对 Prompt 的蒸馏

如果你把反复 Prompt 最终收敛出来的那些约束（“要幂等""余额不能为负""失败不重试”）提前写下来、结构化、固定住——那就是 Spec。

Spec = 对 Prompt 反复试错过程的蒸馏。 把 15 轮对话收敛出来的路径选择，压缩成一份可复用、可审计、可传递的产物。

范式	路径收敛策略	Code 成本	收敛成本	可复用？
古法	人脑逐行决策	高	高（但隐式）	留在人脑，不可转移
Vibe	AI 随机采样 + 反复 Prompt	低	高（反复沟通）	不可复用（对话即弃）
SDD	Spec 提前锁定	低	一次投入，多次复用	✅ 跨人、跨模型、跨时间

实践中 Spec 也是 AI 写的——人表达 Intent，AI 生成 Spec 初稿，人审核冻结。Spec 的价值不在于”人亲手写”，在于它把收敛结果固化成了可复用资产。

Prompt 像口头对话——说完即弃，下次从零开始。Spec 像按业务场景蒸馏出的操作手册——同类需求再来时，直接复用已有的收敛路径。

常见误区：一套 Spec 模板打天下

既然 Spec 是对特定业务场景 Prompt 的蒸馏，那么不同业务场景蒸馏出来的 Spec 结构必然不同。这是很多团队踩的坑——搞一套标准模板，所有需求都往里塞。

举例：

业务场景	Spec 的重心	模板差异
支付/资金	状态机 + 幂等约束 + 异常补偿	必须有资金流转图、对账规则
CRUD 后台	数据模型 + 权限矩阵	Design 层可以很薄
算法策略	输入输出契约 + 效果指标	需要 A/B 实验设计，不需要 DDL
基础设施	性能约束 + 容灾方案 + SLA	必须有容量模型，可以没有 AC

就像不同公司的技术方案模板不一样——Spec 模板也应该按业务域定制。支付团队的 Spec 和内容团队的 Spec，结构可以完全不同。强行统一只会让 Spec 变成”为了填而填”的形式主义。

好的 Spec 模板是从团队真实踩坑中蒸馏出来的，不是从方法论文章里抄来的。

三、Spec 到底是什么——三层产物，不是一份文档

从 Intent 推导：Spec 需要描述什么

上一节推导出了 Spec 存在的必要性。现在问：Spec 里到底该写什么？

一个常见误区：很多人认为只有 Requirement（What）才是 Spec，Design 和 Plan 不算。 这是狭义理解。

从我们的核心模型出发——Intent → Code 中间的所有显式约束都是 Spec：

图中绿色部分全部是 Spec。 在 OpenSpec 的实践中，specs/ 目录下同时存放 spec.md（Requirement）、design.md（Design）、plan.md（Plan）——它们作为一个整体被生成、被审核、被消费。

	狭义 Spec	广义 Spec（本文采用）
包含	只有 Requirement（What）	Requirement + Design + Plan
理论依据	学术定义：spec 描述 what not how	工程现实：Intent→Code 中间的所有显式约束都是 spec
问题	Design 不锁定 → AI 每次选不同路径	—

为什么广义理解更合理？ 因为 Spec 的本质是”在 Intent 和 Code 之间插入的确定性约束”。只要这个约束能帮助路径收敛、能被人审核、能指导 AI 执行——它就是 Spec 的一部分，无论它描述的是 What 还是 How。

未来模型变强，Design 和 Plan 会逐渐变薄——模型能从更少的约束推断更多细节。但当下工程实践中，Design 层仍然是 Spec 中最重要的部分——因为大多数路径爆炸发生在”怎么做”而不是”做什么”。“要幂等”大家都同意，但”幂等怎么实现”才是真正需要锁定的决策。

对应三层 Spec 产物：

层	回答什么	产物	为什么需要
Requirement	做什么、不做什么、验收标准	Boundary + AC（验收标准）	锁定”正确”的定义——没有它，AI 不知道什么叫对
Design	技术方案、架构选型、数据模型	设计文档（DDL / API / 时序图 / 选型对比）	锁定实现路径——在路径爆炸中选定一条，且让人能快速审核方案合理性
Plan	按什么顺序、分几步执行	Tasks 列表 + 依赖关系	当下模型有上下文窗口限制，大任务必须拆分才能保证每步质量

为什么 Spec 必须包含技术方案（Design）

一个常见误解：Spec 只描述 What，不描述 How。这在学术上成立，在工程中不够。

原因很简单——Spec 的核心价值是人审。不审核的 Spec 没有意义。 而人审核需要看到方案才能判断：

• “要幂等”（Requirement）→ 人点头，没问题
• “幂等用 Redis SET NX + 30s TTL”（Design）→ 人才能判断：这个 TTL 够不够？集群故障时 key 丢了怎么办？

如果 Spec 只有 What 没有 How，人审的时候只能审”要什么”，审不了”怎么做”——等到代码出来再审，成本就爆炸了。

所以 Spec 要同时满足两个消费者的需求：

消费者	需要什么	Spec 怎么满足
人（审核者）	快速理解方案全貌，判断路径是否合理	结构化描述：选型对比表、时序图、DDL、边界条件——让人在 10 分钟内做出 approve/reject 决策
AI（执行者）	无歧义的约束 + 足够的上下文来生成代码	编号化 AC、明确的数据模型、API 契约——让 AI 不需要猜

Spec 的设计原则：方便人 Review，同时方便 AI 执行。 两者缺一不可——只方便人看的是技术文档，只方便 AI 读的是 Prompt。Spec 是两者的交集。

为什么需要 Plan（Task 拆分）

这是一个务实的工程约束。2026 年的模型上下文窗口虽然很长（100K-200K tokens），但一次性生成一整个服务的所有代码，质量会显著下降。

Plan 把大任务拆成可独立验证的小步骤，每步聚焦在有限上下文内完成——这是当下模型能力边界下的最优策略。

随着模型能力增强，Plan 这一层会逐渐变薄——模型能在更少的指导下自行拆解。但 Requirement 和 Design 不会消失——因为它们锁定的是人的意图决策，不是模型的执行策略。

SDD 的真正成本不是写 Spec，是审 Spec

这是很多团队上了 SDD 之后撞的墙。

写 Spec 的成本在急剧下降——AI 辅助生成 Requirement、AI 辅助画架构图、AI 辅助拆 Tasks——一份完整 Spec 从 Intent 到初稿，10 分钟搞定。

但审 Spec 的成本没有下降。 审核需要人理解业务上下文、判断方案合理性、预判风险——这些是模型替代不了的（至少当下替代不了）。

当团队并行 5 个需求，每个需求产出 20 条 AC + 一份设计方案——审核者一天要审 100 条 AC。这时候两种退化模式会出现：

• Rubber Stamp（橡皮图章）：审了等于没审，点 approve 只是走流程
• 审核积压：Spec 堆着没人审，AI 等不到 approve 开不了工，效率反而比 Vibe Coding 还低

SDD 的规模化瓶颈不在 AI 侧（生成），在人侧（审核）。 这就是为什么 Spec 必须设计得”方便人快速审”——不是锦上添花，是生死线。

这个问题怎么解？后续篇章会展开。但认知先到位：如果你的 Spec 不能让审核者在 10 分钟内做出决策，那它就不是好 Spec——不管内容多完整。

Spec 不是 Truth——是契约

最后一个认知校准。业界爱说”Spec 是 source of truth，代码只是投影”——这句话在误导人。

一条信息论常识：Spec 若比代码短，就必然省略了某些实现决策。 一份无损到能完整生成全部代码的 Spec，信息量不可能小于代码本身——那它就不是 Spec 了，是一门新的编程语言。

所以 Spec 的正确定位是：

Spec 是契约（锁定关键路径和约束），不是蓝图（描述所有实现细节）。

	Spec（契约）	Code（实现）
回答	系统该做什么、关键路径怎么走	系统具体怎么跑的每一个细节
信息量	故意不完整——只锁关键约束和关键路径	完整但包含大量 AI 自主决策的细节
维护责任	人审核、可演进	AI 生成、可重新生成
判据角色	判定”对不对”的标准	被判定的对象

Spec 是”可接受实现空间”的边界描述——在边界内的实现都算对，边界外的细节由 AI 自主决策。

一个推论：Spec 不维护就会腐烂。 需求变了但 Spec 没更新 → Spec 和代码脱节 → 团队不再信任 Spec → 回到 Vibe Coding。Spec 不是写一次就完事的静态文档——它需要随系统演进而演进，否则就是换了个名字的过期 PRD。

补：和传统技术方案的关系

常见疑问：「这不就是以前的技术方案吗？AI 为什么不能直接根据技术方案生成代码？」

老实说——它可以。 Spec 和技术方案的区别没有很多人想象的那么大。核心差异只有两点：

1. 服务对象不同：技术方案只服务人（可以模糊，人能脑补）；Spec 同时服务人 + AI（AI 不脑补，模糊 = 随机）
2. 验证闭环不同：技术方案写完即弃；Spec 的 AC 要能转测试——因为 AI 生成的代码你没法靠直觉判断对错，需要外部判据

Spec 是技术方案的进化形态：同时满足人的审核需求和 AI 的执行需求，并且自带验证闭环。 你完全可以把现有技术方案稍作结构化改造（加 AC 编号、加边界条件），它就变成了 Spec。门槛没有想象的高。

四、落地指南——不是所有需求都值得写 Spec

不是对立，是光谱

理解了前面的推导，就不会把 Vibe Coding 和 SDD 对立起来了。它们是同一根轴上的不同位置：

选型原则：写 Spec 的成本 < 它省下的返工成本时，SDD 划算。

风险/复杂度	最佳策略	为什么
低（脚本、原型、内部工具）	Vibe Coding	试错成本低，Spec 成本 > 收益
中（功能迭代、CRUD）	Plan Mode + 轻量 Spec	一页 Requirement 锁住核心约束就够
高（支付、权限、数据删除、合规）	Full SDD	返工成本太高，必须前置锁定路径

我们团队的经验：大约 70% 的日常需求落在”中”，用 Plan Mode + 一页 Spec 就够。真正需要全流程 SDD 的只有 15-20% 的高风险需求——但这 15% 如果出事，后果是前面 70% 的总和都兜不住。

3 分钟自测

你正在做的需求，问自己三个问题：

1. 一段 Prompt 能说清所有约束吗？ → 能，且试错成本低 → Vibe Coding 够了
2. AI 生成后你怎么判断对不对？ → 如果答不上来 → 你至少需要 Requirement（AC）
3. 技术方案有多个可选路径，需要人拍板吗？ → 需要 → Design 层也要走审查

三个都是 No → 不需要 Spec。任何一个是 Yes → 你需要对应层级的 Spec。

SDD 不是银弹，是手术刀。不是所有伤口都值得开刀——但当你需要开刀时，创可贴救不了你。

到这里，SDD 的全貌展开了。回到开头那个问题——“SDD 到底有什么用？“——答案是：你已经在做了，只是做得不够系统。 把反复 Prompt 的收敛结果固化、结构化、让它可以被别人审核和复用——这就是 SDD 在做的事。

但一个更尖锐的问题紧跟着来——2026 年模型这么强了，我们真的还需要 Spec 吗？下一篇从第一性原理推导答案。

💬 你和 AI 写代码时，通常要对话几轮才能得到满意的结果？3 轮？10 轮？还是 30 轮？ 留言区说个数字——这个数字越大，说明你越需要把收敛结果固化成 Spec。

下一篇： 2026 年还需要 Spec 吗？OpenAI 说不太写了，但我们的数据说提质 98%。到底听谁的？

内容效果不满意？点此反馈