mine/hexo-blog @ 9eeb05dba0e7dc85d905ebea06809062690db3ee

title: 规范驱动开发不是过时，而是进化 author: Gamehu date: 2026-02-25 22:10:00 tags:

AI
开发流程
Agent categories:
AI ---
AI 思考

引言

最近看到一篇关于规范驱动开发的文章,作者指出一个有趣的现象:规范也是文档,而文档总是过时的。

这话说的没错,但我有一点点不同看法。规范驱动开发不是过时了,而是在AI时代进化了。或者说抛开AI至少在所有重要业务实现的前期阶段是必要的。

一、文档驱动发展的历史脉络

早期困境:口头沟通的代价

在软件工程的早期,项目主要依赖口头沟通和个人记忆。这种方式在小型团队里还行,但一旦团队扩大或人员流动,问题就暴露无遗:

需求在传递中变形
知识随着人员离职而流失
新人入职成本极高
重复造轮子成为常态

文档驱动的出现

为了解决这些问题,文档驱动开发应运而生。它主要经历了几个阶段:

1. 瀑布模型的PRD时代

详细的PRD文档
完整的设计文档
严格的变更流程
优点:标准化、可追溯
缺点:僵化、响应慢

2. 敏捷时代的轻文档

用户故事代替详细PRD
活跃的代码注释
Wiki 风格的文档
优点:灵活、快速迭代
缺点:文档碎片化、维护困难

文档驱动的核心价值

不管哪个阶段,文档驱动都有其不可替代的价值:

知识沉淀:团队知识不会随人员流动而丢失
沟通效率:减少反复沟通的成本
质量保障:明确的规范避免随意改动
可追溯性:决策过程有据可查
新人友好:降低入职门槛

二、AI时代的双重效应

负面影响:过时规范更危险

AI的出现,让文档过时的代价成倍增加。

人类工程师的行为模式:

读到过时文档 → 发现不对 → 会问"这文档好像有问题"
有判断力,会质疑,会沟通
会用实际代码来验证文档

AI Agent的行为模式:

读到过时规范 → 严格执行
缺乏质疑能力,假设规范总是正确的
会按照过时的规范写出过时的代码

问题就在这里:过时的设计文档只会误导碰巧读到它的人类工程师,而过时的规范会误导不知变通的AI Agent。

AI Agent会自信满满地执行一个早已脱离实际的计划,根本不会发现哪里不对。

正面影响:AI成为文档维护的解决方案

但硬币的另一面是:AI恰恰是解决文档维护难题的最佳工具。

为什么这么说?因为文档维护的本质是:让文档与代码/现实保持同步。

而AI擅长的正是:

理解代码:分析代码结构和依赖
生成文档:根据代码自动生成文档
检测差异:对比文档和代码的差异
自动更新:根据代码变化更新文档

这正是文档维护需要的核心能力。

三、规范驱动在AI时代的进化

从静态文档到动态契约

传统的规范驱动是这样的:

人类写规范 → 代码实现 → 规范过时 → 人类更新规范(如果记得的话)

AI时代的规范驱动是这样的:

人类描述意图 → AI草拟规范 → 人类审阅批准 → AI执行并更新规范

关键变化:规范不再是静态的"圣旨",而是动态的"活文档"。

从单向传递到双向反馈

传统模式:

人类 → 规范 → 代码
单向传递,信息单向流动

AI模式:

人类 ↔ 规范 ↔ AI ↔ 代码
双向反馈,信息循环流动

当AI Agent在执行过程中发现:

API不支持规范中假设的方式
有现成的组件可以复用
某些方案不切实际

它会自动更新规范,而不是等人类发现问题。

这就像把任务交给优秀的初级工程师:

发现问题自己更新工单
不会等着你去发现问题
会主动告诉你"之前的假设不对,我用另一种方式实现了"

从人工维护到自动同步

以前,文档更新完全依赖人工。工程师要:

记得更新文档(总是忘记)
抽时间更新文档(总被其他任务挤占)
保持文档准确性(几乎不可能)

现在,AI Agent在执行任务的同时,就能:

检测到规范与实际实现的差异
自动更新规范
说明变更原因

没有人需要专门记着去更新文档。因为更新文档本身就是AI工作的一部分。

四、AI为什么能做得更好?

1. AI不知疲倦

文档维护是隐形工作:

不容易被看见
不容易被奖励
但需要持续投入

人类会厌烦、会忘记、会偷懒。但AI不知疲倦,每次执行任务都会更新规范。

2. AI有上下文理解能力

传统工具(如Swagger生成API文档)只能:

基于代码注释生成
基于代码结构推断
缺乏业务上下文

而AI能够:

理解代码的业务意图
分析代码的依赖关系
推断代码的设计决策
生成更有价值的文档

3. AI可以双向沟通

传统工具是单向的:代码 → 文档。

但AI可以双向:

代码 → 规范(从实现推断规范)
规范 → 代码(从规范生成代码)
规范 ↔ AI(在执行过程中持续对话)

这种双向沟通,让规范真正"活"起来。

4. AI有持续学习能力

随着项目进展,AI可以学习:

哪些规范模式有效
哪些规范会误导AI
哪些细节需要反馈
哪些变更需要批准

通过机器学习,整个系统会越来越智能。

五、如何实现进化的规范驱动?

1. 确立双向维护机制

规范不只是人类写的,也不只是AI写的。双方都要维护。

人类负责:

设定目标和意图
审阅和批准AI草拟的规范
做架构决策和业务判断
处理异常情况和边界条件

AI负责:

根据意图草拟规范
拆解任务和子任务
执行代码实现
更新规范(发现变化时)
反馈执行中的发现

2. 把握反馈颗粒度

这是最难的平衡:

反馈太多:

规范变成噪音
人类习惯性无视
失去规范的意义

反馈太少:

人类失去控制感
不知道AI做了什么
无法及时纠正方向

把握好颗粒度的关键:只反馈那些改变方向的决策。

AI不需要汇报每行代码怎么写,只需要汇报:

发现了现成的组件(不用新建)
API不支持某种方式(换了个实现)
发现了未预料的限制(调整了方案)

3. 建立审查和批准机制

让AI更新规范,需要两个前提:

信任 - 相信AI不会乱改规范机制 - 有审查机制,让人类能看到并批准/驳回AI的更新

缺一不可。

4. 设计增量更新流程

不是每次都从头重写规范,而是:

标记哪些部分被更新了
说明更新的原因
提供变更的上下文
让人类可以快速审阅

六、一个实际例子

来看一个我实际工作中的例子。当我让AI完成一个HTTP接口联调功能后,它自动更新了团队的开发规范文档:

{% asset_img ai-auto-update-spec.png AI自动更新规范文件的Git diff示例 %}

上图展示了一个真实的场景:左侧是原有规范,右侧是AI自动补充的新内容。可以看到AI在HTTP 自动化测试规范部分新增了详细的测试要求,包括:

必须做1个真实接口自动验证 - 每次改动后自动执行业务接口测试
默认验证用例(运营端) - 提供具体的接口调用示例
租户隔离对照测试(必做) - 验证多租户隔离逻辑
命令模板(可直接执行) - 提供可执行的curl命令
失败判定优先级 - 明确问题排查的顺序

这个例子完美诠释了什么是"进化的规范驱动":AI不仅执行代码,还主动更新配套文档,让规范始终保持与实现同步。

再来看另一个更简单的例子。

你写道:

"在设置页面加个能跟随系统偏好的深色模式开关。"

协调Agent读取代码库,草拟一份规范:

添加开关组件
接入preference store
更新CSS变量

你扫了一眼,发现漏掉了"跨会话保存选择",于是补上一句。

你点击批准。Agent开始干活。

15分钟后,其中一个Agent更新了规范:

"在代码库里找到了现成的Theme Provider。已直接接入,未创建新store。"

你审查代码变更(已按Agent和任务清晰分组)。

现在,这份规范反映了实际做出来的东西,而不是最初计划的东西。

最重要的是,没人需要专门记着去更新它。

七、这种模式的推广

不只是代码规范,其他文档也可以这样进化:

API文档

传统:手动编写,过时即误导
进化:AI解析代码和注释,自动生成和更新

架构文档

传统:画完就扔,没人更新
进化:AI分析依赖关系,自动绘制和更新架构图

测试文档

传统:手工编写,用例过时
进化:AI执行测试,自动记录结果和覆盖率

入职文档

传统:一次性编写,快速过时
进化:AI分析项目结构,动态生成入职指南

八、结论

文档维护是软件工程的老大难问题,AI时代这个问题变得更严重了。

但AI也带来了前所未有的机遇。

解决思路不是放弃文档驱动,而是让文档驱动进化:

从静态文档到动态契约
从人工维护到自动同步
从单向传递到双向反馈
从一次性编写到持续演进

规范不是人类单方面写的"圣旨",而是人类和AI共同维护的"活文档"。

这才是规范驱动开发在AI时代的正确打开方式。

参考

原文: https://x.com/dotey/status/2026146560862474482

规范驱动开发的陷阱.md 10 KB History Raw

引言