SSD驱动开发：Spec 到底该长什么样——二十年前的架构师，早就给过答案

公众号名称：dolphin07

作者名称：Dolphin7

发布时间：2026-06-08 19:20

引子

先做个三分钟实验。下面是一份 spec 片段，OpenSpec 跑一个真实需求生成的，格式挑不出毛病：

## Requirements
### Requirement: 异常优先排序
The system SHALL support an `abnormal_first` flag.
#### Scenario: 启用
- WHEN abnormal_first = true
- THEN 异常订单 SHALL 排在前，同等级按创建时间倒序

### Requirement: 异常权重    … 支付失败 > 金额不一致 > 超时，可配置
### Requirement: 分页一致性  … 新排序下分页 SHALL 稳定
### Requirement: 缓存失效    … 权重配置变更 SHALL 失效列表缓存
### Requirement: 权限校验    … SHALL 限定 order:write 角色
### Requirement: 兼容性      … SHALL NOT 改订单状态机与写路径

就一个”订单列表加个排序”的需求。给你三分钟：说清它该不该这么做、哪条规则一旦破了线上会炸。

……卡住了。六条 Requirement 一样规整，要命的那一两条和无关的混在一起，没东西提示你该盯哪。审不动，于是大家凭感觉点头——几天后，线上出事。

这一幕，正是我最近三篇 SDD 落地复盘的同一个病根——《85% 的人说没用》、《落地了效率没提升》、《半年四个坑》：spec 写了，但没人审得动。

我在《85% 说没用》里下过一句狠话：

需要人 review 才能保证正确的东西，恰恰说明它没有自证能力。

代码和测试确实如此——绿就是对，红就是错，不用人看。可业务 spec 躲不掉人审：意图对不对、边界安不安全，机器证明不了，只能人判断。

躲不掉，就只有一条路：让它审得动；而审得动的前提，是先长对样子。

垫一句给新读者：spec 不是详细需求，是意图的契约——把你和 AI 那些一次性 prompt 蒸馏下来的约定，intent → spec → code（细节见主篇）。

说到底，AI 把写代码打到了地板价，稀缺的不再是写，是审。所以这篇只答一个问题：Spec 该长什么样，才审得动？

本文观点（先给结论，再推导）

Spec 应该是”架构设计的极限压缩版”——一屏摘要＋关键图＋契约/不变量＋验收。 只摆该人拍板的决策，用可被校验的形式写出来，让人三分钟审得动。它不是把需求列全的详细文档。

怎么推出来的，三步：① 这道题二十年前的架构师解过；② 他传什么，决定 spec 的内容；③ 执行者换成 AI，决定 spec 的形态。

一、这道题，二十年前的离岸外包解过一遍

intent → spec → code，和当年离岸外包的 intent → 架构设计 → 外包写 code，是同一道题。上下摆一起，差别和共性一眼能看清：

两条链，结构位置一模一样：intent 和 code 中间，都夹着一个看不见、不可信、还会自行脑补的执行者。中间那个框（架构设计 / spec），是同一个位置——你交给执行者、用来约束它的那份契约。

给没经历过那个年代的读者补段背景：2000 年前后，软件离岸外包盛行——需求方在国内，开发团队在印度、东欧、东南亚。隔着大洋、时差、语言，没有今天的实时协作，一次需求往返要按周甚至按月算。一个你见不到面、信不过、还可能随时换人的团队，怎么让它写出能上线的系统？整个行业打磨出了一套成熟到能稳定交付的做法：架构师不甩需求文档，而是交付 HLD/LLD（高/低层设计）、ICD（接口控制文档）、SOW（工作说明书）、UAT（验收测试）。做过乙方或外包的人，对这几个词都不陌生。这套打法，被验证了二十年，撑起过一整个规模数千亿美元的外包产业。

关键就在这儿：架构师交给外包的，从来不是一份详细需求文档，是一套架构设计。所以 spec 的参照物，本就该是”架构设计”，不是 PRD，更不是把需求列成十条 SHALL。

一句话说破：你把 spec 写成了 PRD，可你对面坐的是外包，不是产品经理。

那架构设计里到底有什么、凭什么管用？这才是答案所在。

二、架构师靠什么传意图——这决定了 Spec 的内容

隔着大洋、语言、时区，把活交给一个不可信的远端团队，还能写出上线代码，架构师靠的不是写得多详细，是四样可被校验的东西：

他交付的	传的是	为什么这样传不走样
设计视图（上下文/时序/状态/ER 图）	结构	一段话描述状态机，十人读出十版；一张状态图，谁看都一样
接口契约（字段/状态码/调用时序）	不能错的接缝	唯一零歧义、还能自动验；写歪当场报红
参考实现（样例 + 规范）	默认与风格	规则会被误读，例子难误读——给个样板胜过写十条”要健壮”
验收 + UAT	怎么算做对	不可信的手，只有”可执行的完成定义”挡得住

这是全文的题眼：

架构师传给外包的，从来不是”我想要什么”，是”怎么算做对”。 图、契约、样例、验收——每一样都不是描述，是可被校验的定义。

这里要特别说第一样——图，因为它正在被低估。

软件工程几十年，技术方案设计本来就是靠画图的：上下文图、时序图、状态图、ER 图。这套方法被验证了几十年，偏偏在 vibe coding 里被丢了——大家直接对着 AI 敲字。

而 spec review 这件事，最该把它捡回来。原因很直接：review 是人在 review。 人审长文字会 skim，会”看着都对”；人审图，结构不对一眼就露。图，是为”人审”这件事量身定的形式。AI 时代要让 spec 审得动，画图这件事必须回归。

更进一步，这事可以反过来用：让 AI 多画图，人只审图。 图让 AI 从 spec 或代码生成，人审”这张机器画的图对不对”。确实更省——文字要逐行读、逐行脑补，图扫一眼，缺口和断点自己跳出来。

但有两个前提。一，审图便宜是因为图有损——它只审得出”结构级”的错（漏状态、越界、链路断），审不出阈值、并发、金额精度。所以图不替代契约和验收，是分工：图审结构，契约和测试审细节。二，AI 画的图是它的自我报告——代码和图可能自洽地一起错；人审图不能只看”图自不自洽”，得对着自己的意图审。

把这一列拼起来，spec 的内容就定了：图＋契约/不变量＋范围＋验收。

三、执行者换成了 AI——这决定了 Spec 的形态

内容对标架构设计，但形态不能照抄当年那摞厚文档。因为执行者从”外包团队”换成了”AI”，有三个属性变了，每个都直接改写 spec 的样子：

① 它机械强、判断弱。 AI 语法通过率九成五，安全/业务正确率长期五成上下。→ 人别再花力气审它擅长的代码细节，spec 要把业务判断和红线凸显到最前，让人专审这个。

② 它没有记忆。 每次对话从零开始。→ spec 必须当它的外挂记忆——一份写下来、能版本化、下次直接喂的约定，而不是每次重新 prompt。

③ 它不担责、而且快。 出事只有你，且分钟级就铺开一堆改动。→ spec 不能厚（你审不过来），必须薄到三分钟能审完；验收必须能自动跑（你不能信它一句”测过了”）。

Spec 该薄，不是图省事，是你根本审不过来。 它写得多全不重要，你审得多快才重要。

这里有个现在最大的拧巴，正好印证这一节：

市面上多数 spec 工具，生成的是”给 AI 看的”——长、全、机器友好。可 business spec review 是给人审的。 工具优化错了对象，于是你拿到一份 AI 读着顺、人却审不动的东西。

所以 spec 的形态，要反着工具的默认来调：为人审优化，不为机器生成优化。更薄、图形优先、决策凸显、验收可自动跑、自身当记忆。

四、把这个形状固化下来——Spec 是 prompt 的蒸馏

形状一旦定下来，还有一层红利，正好回应”上了 SDD 却没提效”那个老问题。

vibe coding 是每次都重新 prompt，意图散在一次次对话里，用完即弃。spec 不一样——它是 prompt 的蒸馏：蒸一次，复用很多次。 同一个模块、同一类需求，spec 在那儿，不必每次从头跟 AI 比划。

而且：不同团队蒸出来的内容不一样，但框架是一致的。 支付团队和内容团队的 spec，填的东西天差地别，可骨架都是那一个——一屏摘要＋关键图＋契约/不变量＋验收。

把这个框架沉淀成团队模板，好处是实打实的：

好处	为什么
复用	框架统一，新人照着填，跨人跨需求都能接
省 token	稳定结构 + 复用 spec，不必每次长篇 prompt 重新喂
提效	reviewer 看的永远是同一套结构，审得更快、更稳

一句话：spec 的”内容”随团队变，“框架”必须统一——统一的框架，才换得来复用、省 token 和审得快。

五、所以，Spec 应该长这样

把前面推的收拢，形状就定死了：

一屏摘要        ← 范围：做什么 / 不做什么 / 成功标准
+ 关键图        ← 设计视图：一眼看清改动落点与链路
+ 契约 / 不变量  ← 接口契约：什么绝对不能破（绑成能跑的测试）
+ 验收          ← UAT：怎么证明做对了（能自动验）
（详细背景、备选、边角，全塞进附录）

这四样里，最该花心思、也最体现”AI 时代程序员核心能力”的，是关键图那一行——它的本名叫建模。

我在《10 倍》那篇引过 Martin Fowler 团队的判断：概念建模，会成为核心技能。 道理就在这篇的逻辑里：AI 把”将模型翻译成代码”这一步打到了接近免费，没被打掉的，是”先想清楚系统该长什么样”——边界、流程、状态、数据、契约。这部分，恰恰是古典架构师靠一套图在做的事。

所以这套图不是装饰，是程序员要重新捡起来的手艺：

建模图	给系统建什么模	让 reviewer 一眼审出
上下文图	系统边界与外部依赖	越界、漏依赖
组件 / 模块图	内部结构与职责划分	改动落点、职责错位
时序图	一次流程怎么跨模块走	链路断点、事务/锁边界
状态图	实体的生命周期	非法迁移、漏掉的状态
ER 图	数据关系与约束	外键/基数、金额/库存一致性
部署图	拓扑、灰度、容量	上线、回滚、容量风险

但有个”度”别理解偏了：AI 时代的建模，不是复活大而全的重 UML。 古典架构师有时把图画到事无巨细，反而没人看。这里的重点是建”可审的最小模型”——只画能暴露本次改动风险的那 1–2 张，其余不画。建模的内核也不是”画得漂亮”，是用图逼自己把关键决策定清楚：有哪些状态、哪条迁移合法、哪个字段不能空。

画不出来的图，就是你还没想清楚的地方。 AI 能替你写代码，替不了你把系统想清楚。

举个常见需求：订单列表要支持「异常订单优先」。它不碰状态机、不动数据关系，那就只需要一张时序图＋三条不变量，别的图一张都不画——一屏看完结论，一张图看完链路：

配三条划红线的不变量：

• 开关关闭时，排序和原来完全一样；
• 同一异常等级内，按创建时间倒序；
• 不动订单状态机，不碰支付、退款、履约的写路径。

回到开头那份审不动的六条 Requirement——同一个需求，这一版一张图加三条红线，三分钟你就能判断该不该放给 AI。信息没少：分页、缓存都进了附录；变的只是，该人拍板的决策被拎到最前、用可校验的形式摆了出来。

这就是 spec 该长的样子。而且它不用停在 PPT 上——我把这套形状固化成了团队天天在用的 spec 模板，文末直接附上，可以抄走。

六、五句话带走

1. 前几篇的病根是同一个：没人审得动 spec；而业务 spec 躲不掉人审，那就得让它审得动。
2. intent→spec→code 和当年 intent→架构设计→外包code 是同一道题——spec 该对标架构设计，不是详细需求。
3. 架构师传的不是”我想要什么”，是”怎么算做对”——图、契约、样例、验收，全是可校验的定义，这决定 spec 的内容。
4. 软件工程的画图传统该回归，因为 spec review 是人在审，图是为人审而生的形式。
5. 执行者换成 AI（判断弱、没记忆、不担责）决定 spec 的形态：薄、图形优先、验收自动化、当记忆；框架统一才能复用、省 token、审得快。

附：我团队在用的 Spec 模板（可抄）

光说不练没用。下面是我们团队天天在用的 spec 模板骨架，你可以直接拿去改：

标题：〈功能名〉

## Part I — 背景与目标
- 一句话：做什么、为什么做
- 命名约定（API / DB / 错误码 一张表，统一风格）

## Part II — 系统设计
- 2.1 架构图 + 核心时序图（mermaid）      ← 关键图
- 2.2 协议设计：统一响应 / 错误码表 / 接口协议  ← 契约
- 2.3 数据模型：ER 图 + DDL + 索引说明      ← 关键图 + 契约
- 2.4 方案选型：只保留有真实取舍的决策
- 2.5 资金安全：状态机 + 流转规则（涉资产才写）  ← 不变量 / 红线

## Part III — 质量保障
- 3.1 验收标准：Given-When-Then 表格，AC 编号对照时序图步骤  ← 验收
- 3.2 风险与审查自查表：资金 / 技术 / 数据 / 发布，每项填「设计依据」，
      AI 先填、Reviewer 逐项验                          ← 给人审的入口
- 3.3 测试策略：单测 / 集成 / 并发，对照 AC 编号

## Part IV — 上线发布
- 4.1 上线 Checklist + Seed SQL
- 4.2 灰度与回滚

## 决策确认表                                          ← 把"该人拍板的决策"全拎到这
| # | 决策点 | 影响范围 | 默认决策 | 状态 |
| D-1 | … | … | … | 待确认 |

对一下前面推的：Part II 是图和契约，Part III 是验收和不变量，最后一张决策确认表，把该人拍板的决策全拎到一处——正是”图＋契约/不变量＋验收”，外加一个专门给人审的入口。

它不算短，但没一句废话——每节都是图、表、契约或 AC，reviewer 顺着”图 → 契约 → 不变量 → 验收”扫一遍就审得动。所谓”压缩”，不是短，是零废话、决策前置、全可校验。

两个细节最值得抄：风险自查表那一列「设计依据」——AI 自动填，人只验证”评估过没、引用准不准”，审查从”通读”变成”逐项核对”；决策确认表——把 AI 本会偷偷替你定的默认，全摊到台面等你拍板。这两样，就是”让人审得动”落到纸面的样子。

下一篇《写完 Spec 只是开始：用 eval 守住 spec 和代码不漂移》，怎么把 spec 变成一直在跑的评测基准，让 spec↔code 的漂移自动暴露出来。

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