唯一能信任的文档是代码,不是 Spec

唯一能百分百信任的文档，就是代码本身。设计文档、更新日志、README、架构图，这些东西写完几乎就过时了。

那 Spec 呢？

最近关于 SDD（Spec-Driven Development，规格驱动开发）有很多争论。SDD 确实解决了几个真实问题：明确的 Spec 能控制 AI 的发散，防止它在实现复杂业务时自由发挥；Spec 可以作为高效的前后端契约，减少联调摩擦；规格还能沉淀为可执行资产，驱动代码生成和自动化测试。

但 SDD 真的有这么好吗？

SDD 可能没那么好

最近读到一篇文章，What spec-driven development gets wrong^[1]，观点让我很有共鸣。

文档必然过时

让一份文档跟上系统的变化，是一项持续性的成本，但工程师天生就是干一波就走的。写完文档，上线功能，转头去做下一件事。”更新文档”是没人看到的隐形工作，每天都在和其他事情抢优先级，而且几乎每次都输。

他们试过流程，试过工具，试过把它变成团队价值观。都没用。因为他们一直在要求人类做一件人类几乎不会做的事。

Spec 也是文档

SDD 的理念本身没问题：在使用 Coding Agent 时，先把需求写清楚再让它们去干活。显然比往聊天窗口里粘贴 Prompt 然后听天由命要靠谱得多。

但 Spec 终究是一份文档。而文档会怎样，我们刚才已经说了。

过时的 Spec 比过时的文档更危险

一份过时的设计文档，顶多误导下一个碰巧读到它的工程师。但人会质疑。

而一份过时的 Spec 会误导不懂分辨的 Agent。它们会自信满满地按一个已经不符合现实的方案去执行，而且不会发出任何警告。

关键不是要不要写 Spec，而是谁来维护

如果 Spec 只是人写给 Agent 的单向文档，那它和其他文档没有区别，迟早过时。

他们的实践是让 Spec 变成双向的：人负责描述意图和审批方向，Agent 在执行过程中把发现的偏差和实际决策写回 Spec。

比如你写了个需求”添加暗黑模式切换”，Agent 拆完任务开始执行，过程中发现代码库里已经有主题 Context Provider，就自己更新 Spec：”直接接入已有 Provider，不再新建 store。”你审核通过，Spec 就自动反映了实际构建的结果。没人需要”记得去更新文档”。

软件行业里每一次”文档先行”的尝试都失败了，原因都一样：它要求开发者做一项没人看到、没人奖励的持续性维护工作。

SDD 也会因为同样的原因失败，除非 Agent 也承担起维护的那一份。

既然 Agent 能写代码，它们就能更新计划。让它们去做。

但你还是要写规格

说了这么多，我并不是说不要写规格。

你仍然需要写高层次的架构规格：项目结构、代码规范、技术栈选择等等。这部分由人来维护。

但实现层面的细节规格，交给 AI。

我的做法是让 AI 生成一个 specs 目录，完全由 AI 自己迭代维护。改代码前，先读相关 spec 了解上下文。改完代码后，更新 spec 反映最新状态。读、改、写，循环往复，形成自我迭代的闭环。

人管架构，AI 管细节。这就是我理解的双向维护。

最后

SDD 确实是一个不错的范式，但人类的天性与持续维护文档的要求是完全背道而驰的。如果规格只由人单向维护，这些资产产出即过时。

所以用 SDD，但必须是 AI 自我迭代维护的 SDD。

如果你觉得这篇文章对你有帮助，欢迎点赞、分享，你的支持是我持续创作的最大动力！

引用链接

[1] What spec-driven development gets wrong: https://x.com/augmentcode/article/2025993446633492725