规范驱动开发的陷阱.md 14 KB
title: 规范驱动开发不是过时，而是进化 author: Gamehu date: 2026-02-25 22:10:00 tags:
- AI
- 开发流程
- Agent categories:
- AI
---
AI 思考
最近看到一篇关于规范驱动开发的文章，作者指出一个有趣的现象：规范也是文档，而文档总是过时的。
这话说的没错，但我有一点点不同看法。规范驱动开发不是过时了，而是在AI时代进化了。
不过，在讲怎么进化之前，我想先聊一个更底层的问题——为什么有时候规范是最新的，效率还是没提升？
一、先讲一个快手的案例
前段时间快手技术团队发了一篇复盘，讲他们万人组织怎么用AI提升研发效能。看完我挺有感触的。
他们2024年就全员推广AI编程工具，代码生成率干到了30%+，部分业务线甚至40%+。调研结果显示，开发同学主观体感效率提升了20-40%。
看起来很美对吧？
但看组织层面的数据：需求交付周期基本没变，需求吞吐量也没明显提升。
快手把这个问题叫做"AI研发提效陷阱"：
用AI开发工具 ≠ 个人提效 ≠ 组织提效
这事给我提了个醒。我们聊规范驱动开发，不能只聊"规范怎么保持最新"，还得聊"规范怎么真正驱动交付"。
不然就像快手早期那样——工具用得很溜，但组织效率没动静。
二、文档驱动发展的历史脉络
早期困境：口头沟通的代价
在软件工程的早期，项目主要依赖口头沟通和个人记忆。这种方式在小型团队里还行，但一旦团队扩大或人员流动，问题就暴露无遗：
- 需求在传递中变形
- 知识随着人员离职而流失
- 新人入职成本极高
- 重复造轮子成为常态
文档驱动的出现
为了解决这些问题，文档驱动开发应运而生。它主要经历了几个阶段：
1. 瀑布模型的PRD时代
- 详细的PRD文档
- 完整的设计文档
- 严格的变更流程
- 优点：标准化、可追溯
- 缺点：僵化、响应慢
2. 敏捷时代的轻文档
- 用户故事代替详细PRD
- 活跃的代码注释
- Wiki 风格的文档
- 优点：灵活、快速迭代
- 缺点：文档碎片化、维护困难
文档驱动的核心价值
不管哪个阶段，文档驱动都有其不可替代的价值：
- 知识沉淀：团队知识不会随人员流动而丢失
- 沟通效率：减少反复沟通的成本
- 质量保障：明确的规范避免随意改动
- 可追溯性：决策过程有据可查
- 新人友好：降低入职门槛
但这里有个隐含假设：文档是给人看的，人会判断、会质疑、会沟通。
三、AI时代的三重效应
第一重：过时规范更危险
AI的出现，让文档过时的代价成倍增加。
人类工程师的行为模式：
- 读到过时文档 → 发现不对 → 会问"这文档好像有问题"
- 有判断力，会质疑，会沟通
- 会用实际代码来验证文档
AI Agent的行为模式：
- 读到过时规范 → 严格执行
- 缺乏质疑能力，假设规范总是正确的
- 会按照过时的规范写出过时的代码
过时的设计文档只会误导碰巧读到它的人类工程师，而过时的规范会误导不知变通的AI Agent。
第二重：AI成为文档维护的解决方案
但硬币的另一面是：AI恰恰是解决文档维护难题的最佳工具。
为什么这么说？因为文档维护的本质是：让文档与代码/现实保持同步。
而AI擅长的正是：
- 理解代码：分析代码结构和依赖
- 生成文档：根据代码自动生成文档
- 检测差异：对比文档和代码的差异
- 自动更新：根据代码变化更新文档
第三重：个人提效≠组织提效（新增）
这是快手案例给我最大的启发。
我们假设这样一个场景：
- 规范是最新的，AI能自动维护
- 每个开发同学都用AI写代码，个人效率提升30%
- 但需求交付周期还是老样子
问题出在哪？
规范只解决了"做什么"和"怎么做"，但没解决"怎么协作交付"。
快手早期的"智能化1.0"就是这个状态：推广AI编码工具、AI测试工具、AI CR工具，单点看每个工具都很好用，但端到端的流程没打通。
就像一条高速公路，每辆车的引擎都升级了，但收费站还是人工收费，整体通行速度能快吗？
四、规范驱动在AI时代的进化
从静态文档到动态契约
传统的规范驱动是这样的：
人类写规范 → 代码实现 → 规范过时 → 人类更新规范（如果记得的话）
AI时代的规范驱动应该是这样的：
人类描述意图 → AI草拟规范 → 人类审阅批准 → AI执行并更新规范
关键变化：规范不再是静态的"圣旨"，而是动态的"活文档"。
从单向传递到双向反馈
传统模式：
- 人类 → 规范 → 代码
- 单向传递，信息单向流动
AI模式：
- 人类 ↔ 规范 ↔ AI ↔ 代码
- 双向反馈，信息循环流动
当AI Agent在执行过程中发现：
- API不支持规范中假设的方式
- 有现成的组件可以复用
- 某些方案不切实际
它会自动更新规范，而不是等人类发现问题。
从单点规范到端到端流程（新增）
这是结合快手经验的新认识。
以前我们理解的规范，主要是实现规范——接口怎么设计、代码怎么写、测试怎么覆盖。
但AI时代，规范应该延伸到端到端的交付流程：
- 需求分析规范：AI怎么理解需求、怎么拆解任务
- 协作规范：AI Agent之间怎么分工、怎么交接
- 质量门禁规范：什么情况下可以进入下一阶段
- 反馈规范：AI怎么汇报进度、怎么暴露阻塞
快手"智能化2.0"的核心转变，就是从"推广AI工具"回归到"如何用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代码生成率、AI CR采纳率
结果指标：需求交付周期、需求吞吐量
健康度指标：代码质量、线上稳定性
关键是：不能只盯着过程指标。
AI代码生成率30%固然好看，但如果需求交付周期没变，说明规范只在编码环节生效，没有打通全流程。
度量不是为了考核，是为了验证规范是否真的驱动了交付。
5. 设计增量更新流程
不是每次都从头重写规范，而是：
- 标记哪些部分被更新了
- 说明更新的原因
- 提供变更的上下文
- 让人类可以快速审阅
七、一个实际例子
来看一个我实际工作中的例子。当我让AI完成一个HTTP接口联调功能后，它自动更新了团队的开发规范文档：
{% asset_img ai-auto-update-spec.png AI自动更新规范文件的Git diff示例 %}
上图展示了一个真实的场景：左侧是原有规范，右侧是AI自动补充的新内容。可以看到AI在HTTP 自动化测试规范部分新增了详细的测试要求，包括：
- 必须做1个真实接口自动验证 - 每次改动后自动执行业务接口测试
- 默认验证用例（运营端） - 提供具体的接口调用示例
- 租户隔离对照测试（必做） - 验证多租户隔离逻辑
- 命令模板（可直接执行） - 提供可执行的curl命令
- 失败判定优先级 - 明确问题排查的顺序
这个例子完美诠释了什么是"进化的规范驱动"：AI不仅执行代码，还主动更新配套文档，让规范始终保持与实现同步。
但更重要的是，我开始关注另一个指标：这个规范更新后，团队的整体交付节奏有没有变化？
不只是"规范是最新的"，而是"最新的规范有没有让协作更顺畅"。
八、这种模式的推广
不只是代码规范，其他文档也可以这样进化：
API文档
- 传统：手动编写，过时即误导
- 进化：AI解析代码和注释，自动生成和更新
架构文档
- 传统：画完就扔，没人更新
- 进化：AI分析依赖关系，自动绘制和更新架构图
流程规范
- 传统：写进Wiki，变成摆设
- 进化：AI在执行中识别瓶颈，建议流程优化
流程规范特别值得强调。快手的经验表明，AI时代的流程规范应该回答这些问题：
- 需求怎么拆解成AI可执行的任务？
- 多个AI Agent怎么协作？
- 人类在什么节点介入？
- 怎么度量端到端效率？
这些不是技术细节，是组织效能的基础设施。
九、结论
文档维护是软件工程的老大难问题，AI时代这个问题变得更严重了。
但AI也带来了前所未有的机遇。
解决思路不是放弃文档驱动，而是让文档驱动进化：
- 从静态文档到动态契约
- 从人工维护到自动同步
- 从单向传递到双向反馈
- 从单点规范到端到端流程
- 从主观感觉到数据度量
规范不是人类单方面写的"圣旨"，而是人类和AI共同维护的"活文档"。
但记住快手那个教训：规范保持最新只是第一步，让规范真正驱动端到端交付，才是最终目标。
不然就会出现那种尴尬的局面——每个环节都很高效，但整体就是快不起来。
参考
原文：https://x.com/dotey/status/2026146560862474482
快手研发范式复盘：《快手万人组织 AI 研发范式 跃迁之路：从平台化、数字化、精益化到智能化》
相关阅读：