ARTICLE · 1300631

【SDD系列09】文档就是生产力!《文档驱动开发操作实践》

发布时间：2026-11-03 09:53:23 最近访问：2026-11-03 09:53:24

SCM 双栈迁移折腾记 · 第 9 讲（9月3日回看方法，用前文反例检验可复用动作）

作者：老高标签：AI实战 / SDD方法论 / 工程护栏 / 反例复盘 / 创业笔记

书接上回。

上一讲我们翻开了 7—8 月份的生产运维台账，看清了系统上线后的真实运行状态。到了 2026 年 9 月 3 日，我们把从 5 月份以来的全部实践浓缩成了一份 19 页的总结材料——《文档驱动开发操作实践》。

每次我跟外部的技术朋友聊起“我们用文档驱动开发（SDD）在 7 周内迁完了 1100 多个接口、停掉了老系统”，十个人里有八个人第一反应都是皱眉头：

“老高，别逗了！我们公司最烦写文档了，程序员写完代码补个接口文档都跟要命一样，而且写完三天就过期，你们怎么可能靠‘多写文档’把重构速度提上去十倍？”

问得好！如果“文档驱动开发”等于“让程序员多写八股文、事后补交作业”，那它百分百是形式主义的毒药。

事实上，在第 2 讲里你们已经看到了：我们在 5 月 13 日搞的第一版“五件套”，就是因为随手多建了几份散落文档，不到五天就出现了信息漂移，差点让整个团队乱了套。

那我们后来跑通的这套办法，核心到底是什么？就一句话：不是“多写文档”，而是把文档变成卡在代码前面的硬契约——写什么、谁签字、怎么验真、什么时候必须关掉旧规则，每一条动作都是被前面摔得鼻青脸肿的反例逼出来的！

今天第九讲，咱们不讲虚头巴脑的理论，直接拿前八讲里真实踩过的反例当试金石，把这套办法拆成“写什么、谁确认、如何验、何时不能照搬”四张可直接抄作业的清单。

一、第一问：到底“写什么”？（别建垃圾堆，只立五个咬合齿轮）

很多团队一提写文档，就让每个人建个个人文件夹写周报、写心得。在多个人类工程师 + 十几个 AI Agent 日夜并行的战场里，散落的文档就是噪音，甚至会误导后面接手的人。

这就好比开连锁餐厅：你不能让每个厨师在墙上随便贴菜谱，必须全店只认一本《中央厨房标准操作手册》。我们在 5 月 23 日定型、并一路沿用到 9 月份的文档体系，只有环环相扣的五个咬合齿轮：

配图 01SDD 五齿轮：从文档契约到交付门禁

文档不是写给领导检查的作业，而是让多个人和十几个 AI Agent 不撞车的交通信号灯。

1. 接口四件套（共沉淀 2,121 份）：动手写码前，先交出业务理解与测试计划

每一个待迁移或待开发的接口，必须按顺序生成四份文件：

01-业务理解（877 份）
：逐行读懂老代码，写出状态机、隐藏钩子、NC 推送和异常分支。硬规矩：必须用业务大白话写，严禁直接粘贴 Java 源码充数！

反例检验
：第 4 讲里，为什么销售计划的“关单释放库存分支”会漏迁？为什么“已发货/已退货”会被偷懒打包标成“跨模块未迁置 0”？就是因为没把每个字段的数据源和钩子在《业务理解》里扒到底！

02-测试计划（363 份）
：写代码之前，先声明这个接口适用 6 层测试里的哪几层，边界用例是什么，并逐条勾选 12 项防坑清单。
03-迁移结果（510 份）与 04-真实用例（371 份）
：迁完记下各层绿灯状态、遗留偏差与验证过的真实单据号。

2. 单一事实源 SoT（14 个全局文件 + 每模块 4 本台账）：任何口径只在一处定义

全局顶层 SoT
：红线规则、7 步标准流程、6 层测试定义、灰度路由手册、方法论剧本、5 分钟新人入门与维护协议。
每模块固定 4 本台账
：范围表（ENDPOINTS）、完成度签字表（COMPLETION-STATUS）、共性踩坑表（ISSUES-LOG）、切流操作手册（CUTOVER）。
三条保命铁律
：

历史过期的文档一律塞进 archive/ 归档目录，标明“永不更新”；
想加新规则必须改现有台账，严禁随手新建散落文件；
接手任何模块前，严禁盲信看板字面状态，必跑“接手前四步代码库核查”（第 2 讲费用池模块差点重复造轮子白干两天的血泪教训）！

3. 踩坑即红线（6 个模块 1,235 行踩坑记录 → 全局免疫）

一人踩坑，当天写进模块的《共性踩坑表》；凡属跨接口的共性坑，立刻升格进全局红线或全局配置——比如第 4 讲开发者L抓出新版框架自增主键带旧 ID 插入撞车，当天就升格为全局配置开关 insertIgnoreAutoIncrementColumn = true，后面所有模块直接免疫。

二、第二问：到底“谁确认”？（AI 算得再快，这三件事必须人类拍板）

有了 AI Agent 之后，最容易犯的第二个错误是“无人驾驶幻觉”——觉得既然 AI 也能写代码、也能跑测试，干脆让它自己审自己、一路自动合进生产分支算了。

我们的实践证明：AI 写得越快，“人的签字确认”就越不能省，但人的精力必须花在刀刃上！

1. 上线就绪的硬定义：`自动化测试全过 ∩ 人工真环境审核过（AND）`

这是开发者L在 5 月 23 日拍下的铁律：

第一条腿（机器）
：该接口适用的自动化测试层全部绿灯（不适用标 NA 也必须由模块负责人拍板留痕，不许 Agent 自己跳过）；
第二条腿（人审）
：模块负责人（开发者L、开发者C、开发者Z）在真实测试/仿真环境走单，逐接口在完成度台账上签字画押（如结算费用模块：开发者L审 34 个 + 开发者Z审 24 个 + 开发者C审 47 个 = 105/105；采购模块：开发者C连续两晚验完 176/176）。
反例检验
：第 3 讲里，切流前 6 层自动化测试 100% 全绿，正是开发者C在真环境的人工手测，当场拦下了 CAST AS BIGINT 语法错、itemMap 未摊平、EasyPOI 缺校验器、Redis 哨兵写死这 4 个真 Bug！

2. 存量死活判定与业务规则空白，100% 归人拍板

当 Agent 遇到以下三种情况时，必须自动暂停，只准列证据和选项，严禁替业务做决定：

情况 A（功能死活未知）
：第 5 讲停老栈再审时，发现额度模块在生产库 2 年 0 行数据。Agent 绝不自己判死或硬补，而是交由开发者C拍板“额度模块整体弃用下线，电子卡验真保留补分支”。
情况 B（业务规则半残或与税法冲突）
：第 7 讲台账调整生产 0 单，Agent 写出 PRD 列出 9 个决策点等业务负责人G拍板；猫超茅台 -54,249.54 元负数发票，技术上删 3 行前端代码就能放开，但因为触碰增值税蓝字发票禁负红线，Agent 列出 5 套方案，写 0 行代码等财务定口径。
情况 C（历史人工数据口径不一）
：第 7 讲关联交易预付 27 张人工凭证里 25 张按整单算、2 张按明细算差 1—2 分钱，必须请开发者Z拍板“统一按整单算 + 写死触发范围”。

配图 02AI 执行与人类拍板的权责边界

把 90% 的体力活交给 AI 狂飙，把 10% 关乎真金白银的拍板权死死握在人类手里！

三、第三问：到底“如何验”？（撕掉“假绿灯”的六条验真铁律）

前面八讲里，我们吃过最大的亏，不是“测试报错”，而是“明明显示成功、显示绿灯，结果上线却是坏的”！如果你要把这套方法搬回自己团队，请一定把下面这 “撕掉六种假绿灯” 的验真铁律贴在工位上：

假绿灯陷阱	我们在项目里栽过的真实跟头（前文反例）	可复用的验真铁律（怎么破）
1. H2 绿 ≠ 真 MySQL 绿	第 3 讲：`CAST(CODE AS BIGINT)` 在 H2 内存库下全绿，上真 MySQL 报 1064 语法错，4 个新增接口全崩。	方言敏感 SQL（`CAST`/日期/聚合/空 `IN ()`）必在真 MySQL 或生产只读库跑改前/改后对比（如第 8 讲排除赠品静态展开实测）。
2. 单测绿 ≠ 断言真有效	第 7 讲：在途额度单测只检查了未渲染的参数值集合，故意删掉 `WHERE` 或把在途/已核两列值互换，单测居然还是绿的；第 3 讲异常处理器把空指针吞成 `success(null)` 造出 12 个假绿。	关键写路径必做“变异测试” ：故意删掉 `WHERE`、交换字段值、改反排序，看测试会不会变红；严禁异常处理器把错误包成 HTTP 200 成功。
3. 空表测过 ≠ 分页/取数对	第 4 讲：修复销售域 8 处分页时，在测试机测通过，上生产可退货查询返回 `total:39175, size:0`（空列表）——因为测试库该表是 0 行，“空=对”掩盖了返回值写成 `List` 未回填的 Bug。	验证查询与分页，测试样本必须既有大于每页条数的多页数据，又能验证非空回填；大渠道性能必用大数据量样本测。
4. 产物里有 ≠ 运行时生效	第 6 讲：`grep` 生产 CSS 包确认有 `height:14px`，但页面被全局 `5px !important` 压死；第 5 讲：管理台显示单活参数，但旧版 RabbitMQ 存而不执行；第 8 讲：`mvn \| tail; echo $?` 拿到 `tail` 的 0 误以为编译成功。	CSS 必看浏览器 F12 计算样式；构建脚本拿退出码严禁隔管道，打完 jar 包必用字节码反编译四象限法（新包有/旧备份包无）核实！
5. 查表为 0 ≠ 没丢数据	第 8 讲：盘点张裕库存日快照历史时用 `INNER JOIN` 得出“仅 3 格异常”，漏掉了 13 个“整行缺失”的格子；渠道在途巡检以在途表为主表，看不见“首次发货就消费失败未入表”的盲区。	查缺失、做巡检，必须以“源头业务表”为主表 `LEFT JOIN` 目标快照表，判 `右表主键 IS NULL` ，严防幸存者偏差！
6. 本地代码 ≠ 线上真代码	第 8 讲：查张裕库存和 1% 税率案时，共享工作区落后线上主分支 80~128 个提交，导致开发者L 20 天前已修好的全局锁没被看见。	排障和改码前第一件事：拉取远端最新代码并直接读线上分支，用独立工作区（`worktree`）干活，严禁轻信本地旧目录！

配图 03撕掉六种假绿灯

不怕测试亮红灯，就怕一屋子假绿灯哄着你带病上生产！

四、第四问（高潮）：何时“不能照搬”？（看清方法的边界与衰减）

讲完了哪些可以照着做，咱们最后必须泼一盆清醒的冷水：这套办法里，有哪些东西是有严格保质期的？甚至有哪些地方连我们自己做着做着都出现了磨损？

1. “严格 1:1（连空指针都原样复刻）”千万不能照搬到日常新需求里！

在第 2 讲里，我们立下了“老栈抛空指针新栈也必须抛空指针，不许加判空防御”的铁律。但请一定记住：这条反直觉规则，只在“新老双栈并存、要求外部报文与异常表现 100% 等价”的平移窗口期成立！

一旦遇到老栈本身存在致命架构或并发缺陷（比如第 4 讲结算单 7000 万行巨表慢查询、第 5 讲双实例下失效的 4 个单机锁 synchronized、以及把 16 万行 Excel 全量装进内存导致服务器内存溢出崩溃的假流式导出），经负责人明确拍板后，就必须启动“缺陷复刻例外条款”动手改造！
一旦老栈停用、进入新功能开发或重做期（比如第 7 讲的费用核报发票单、第 8 讲的台账调整重做），就必须立刻把“防御性编程肌肉记忆”重新打开——这时候再不写空值守卫、不加事务后解锁和 FOR UPDATE，那就是纯粹的渎职了！

2. 诚实承认“文档执行强度衰减”：为什么测试计划只有理解文档的 41%？

在 8 月 29 日拉全仓统计数据时，我们发现了一组非常耐人寻味的数字：在 migrations/ 目录下的 2,121 份接口四件套里：

01-业务理解
有 877 份（覆盖了超过 3/4 的接口，说明“先读懂老代码再动手”大家确实坚持下来了）；
03-迁移结果
有 510 份；
04-真实用例
有 371 份；
而 02-测试计划（写代码前先定的测试方案）只有 363 份——仅仅是业务理解文档的 41%！

为什么会出现 877 → 510 → 363 的阶梯式衰减？因为在成本和采购等前期模块打样时，大家严格遵守“先写理解、再写测试计划、最后写代码”；可到了 6 月中旬多模块冲刺收口的后期，随着套路熟练和工期压力，部分模块出现了“写完理解文档直接写代码和单测，省掉单独的测试计划文档（先码后档回潮）”的现象！同样，在维护单一事实源台账时，我们也发生过“文档漂移”（比如切流手册上的完成数一度停在 92/105，滞后于完成度总表的 105/105），因为目前还靠人自觉同步，没有加上流水线自动拦截。

把这 41% 的衰减和文档漂移原原本本写进总结报告，不是为了自我贬低，而是为了告诉所有想复用这套方法的人： 任何工程纪律，如果不靠自动化门禁（比如提交代码时自动检查缺文档不许合并）锁死，单靠人的自觉，在高压冲刺期一定会发生磨损！