先画图纸，再让 Agent 施工：Spec-Driven 开发实战

Agent 时代最贵的浪费：让顶级施工队「边想边盖」

你有没有算过一笔账：一个 vibe coding 项目里，真正花在「写代码」上的 token 占多少，返工占多少？我的体感是，返工至少占一半。而返工的根因，十次有九次不是模型不行，是你在开工前没把意图说清楚。

这里有个残酷的换算：agent 理解错了需求，错的不是它，是你。Agent 是这个时代最强的施工队，但它有个致命特点——它从不质疑图纸。你给它一句「做个好看的后台」，它真就闷头盖出一栋楼，盖完你才发现朝向反了。然后你让它拆了重盖，token 就这么烧掉了。

我的判断是：prompt 是口头交代，spec 是施工图纸。口头交代适合三句话能讲清的事；凡是超过一小时工作量的任务，都值得先画图纸。把这句话反过来读也成立：如果你发现自己总在跟 agent 返工扯皮，问题不在提示词技巧，在你跳过了画图纸这一步。

能驱动 Agent 的规格长什么样：5 件套，不多不少

先说两种常见的「伪规格」。一种是 50 页需求文档——agent 读到第 10 页就开始幻觉，后面全靠编；另一种是散文式描述——「系统应该优雅地处理用户请求」，这种话对 agent 等于没说，它会用自己的想象填满所有空白。

好规格的标准只有一个：agent 读完之后，它输出的 Plan 里每一步都能指回规格里的某一条。指不回去，规格就是废纸。围绕这个标准，一份规格只需要 5 件套：

• 目标与非目标：用两句话讲清「这是什么」和「这不是什么」。非目标比目标更重要——它是 agent 的刹车片，没有它，agent 会一路把功能做到你没想过的地方去。
• 用户故事 + 验收标准：每个故事配 Given-When-Then 验收标准。没有验收标准的故事，agent 会自己发明一个，然后理直气壮地告诉你「完成了」。
• 数据与接口契约：表结构、字段、API 的输入输出。这是 agent 不敢乱发挥的部分，越精确越好。契约是规格里唯一值得写到字段级别的东西。
• 不做清单：明确列出「这次不做的三件事」。这是防止范围蔓延最便宜的保险，比你在 review 时喊停便宜十倍。
• 开放问题与决策日志：拿不准的先记下来，做了决定的写下「为什么」。一个月后当你想问「当初为啥这么定」，这条能救命。

最小模板可以直接抄：

## 目标 / 非目标
## 用户故事（每个配验收标准）
## 数据与接口契约
## 不做清单
## 开放问题 / 决策日志

一页纸能写完，就不要写两页。规格的长度和它的效力成反比——agent 对超过上下文窗口一半的文档，阅读理解能力是断崖式下跌的。

开发循环：Spec → Plan → Task → Verify，顺序不能乱

这是整篇文章最重要的一段。规格驱动不是「写完文档再开工」的形式主义，而是一个循环，每一步都有明确的产出和检查点：

1. Spec（你写）：一页纸起步。agent 可以帮你整理措辞、补全格式，但拍板的是你。意图的所有权永远在人手里，这是不可外包的。
2. Plan（agent 出，你审）：让 agent 先输出执行计划，你审计划，不审代码。这是性价比最高的 review——看 20 行计划，比看 2000 行 diff 省十倍时间。计划里有你不同意的步骤，现在改掉，成本几乎为零。
3. Task（拆小步）：把 plan 拆成可独立验证的小步，一步只做一件事，做完就验收。大步快跑是返工的温床。
4. Verify（对照 spec 验收）：验收标准在 spec 里写死了，agent 抵赖不了。「跑起来了」不算数，「spec 里第 3 条验收标准通过了」才算数。

循环之上还有 4 条铁纪律：

• 计划先行：不许 agent 跳过 plan 直接写代码。跳过 plan 的 agent，就像不看图纸的施工队——盖得越快，拆得越贵。
• 可追溯：plan 的每一步标注对应 spec 条目。对不上的步骤，要么补 spec，要么删步骤。没有出处的步骤，就是需求蔓延的种子。
• 偏离先改 spec：执行中发现 spec 错了？停下来，先改 spec，再让 agent 基于新 spec 出变更 plan。永远不要让代码和 spec 朝两个方向跑——那是技术债的源头，也是三个月后没人敢动这块代码的原因。
• 验收看 spec：demo 时对照验收标准一条条过。「看着像」不算数，「测着对」才算数。

Agent 时代，人的工作从写代码变成了写规格和审计划。接受这个转变，生产力才会真的翻倍；拒绝它，你只会得到一个烧 token 更快的自己。

规格是活文档，不是开工仪式

规格最常见的死法：写完就扔进 docs/ 文件夹吃灰，代码朝另一个方向狂奔。三个月后 spec 和代码没有一句话对得上，它就从资产变成了负债——后人还要花时间分辨哪句是真的。

解法很土但有效：spec 进 git，跟代码同版本；需求变更的标准动作是「先改 spec，再让 agent 出变更 plan」；决策日志持续记录「为什么这样定」。规格和代码的版本永远一致，这是底线。

一个简单的健康检查：如果你发现 spec 已经两周没更新了，说明它已经死了——要么复活它，要么删掉，别留着骗自己。死的文档比没有文档更贵，因为它提供虚假的安全感。

什么时候别写规格：诚实面对成本

规格不是免费的。一页纸规格也要 30 分钟，这 30 分钟花得值不值，看代码的寿命。我的标尺：代码寿命超过一周，就值得一份一页纸 spec；一次性脚本、探索性 spike、扔掉也不可惜的原型，不值得——直接 vibe，怎么快怎么来。

但注意这个陷阱：「先快速做个原型验证想法」是最常见的借口。原型一旦活下来，就会变成祖传代码，而祖传代码最缺的恰恰是当初没写的 spec。如果你预感这个原型有 30% 的概率转正，那就写一页纸——这是你能买到的最便宜的保险。

最后一句：spec-driven 不是慢，是把返工的时间前置了。前置的 30 分钟，能买回来后面三小时的扯皮。这笔账，算得过来的都算得过来。