——文档不是终点，是改造的起点
系列导读：这是《老项目如何引入文档驱动》系列的第 5 篇。前四篇我们聊了为什么需要文档驱动、如何用 AI 理解代码、如何写出第一份 MVD、如何让文档持续维护。现在，更激动人心的事来了——如何用文档驱动老项目的重构？
小张的意外发现:文档成了"照妖镜"
小张是我们团队的高级工程师。3个月前,他按照前三篇的方法,给支付模块写了一份MVD。
写完后松了口气:"终于把文档补上了,新人应该能看懂了。"
但2周后,新人小王拿着文档来找他:"张哥,我按照文档理解的流程,和代码对不上啊。"
小张仔细一看:
文档说支付状态有5种,代码里有8种。
文档说回调逻辑在PaymentCallbackHandler,但代码里:
-
支付宝在PaymentCallbackHandler
-
微信在WeChatService
-
银行卡在BankCardController
他花了2天写的文档,现在看起来更像是"对现实的误解"。
但他很快意识到:不是文档写错了,而是代码本身就有问题。
写文档的过程,强迫他理清楚"应该是什么样",结果发现代码早就"走样"了。
这就是很多人写完文档后遇到的困境:文档像一面镜子,照出了代码的问题,但不知道怎么改。
小张的真实困境：重构之路并不顺利
你可能以为：小张从此开始了一帆风顺的重构之旅。
错了。
第 2 周：
小张开始细化问题清单时，发现问题远比想象的多。
不是 5 个问题，而是 12 个。
他开始怀疑：这些都要改吗？改得完吗？
团队 Leader 也来问：“你花了 2 周在文档上，什么时候开始做需求？”
第 4 周：
正当他准备重构状态管理时，客户催新需求：“这周五必须上线！”
重构计划被迫暂停。
他花了 3 天赶需求，又花了 2 天修 bug。
重构？只能先放一放。
第 5 周：
恢复重构后，他发现 AI 给的方案有漏洞。
AI 建议“将状态转换逻辑迁移到状态机”，但没考虑到数据库中已有的 8000 条历史订单。
迁移状态机？历史数据怎么办？
他花了 3 天重新设计兼容方案。
第 8 周：
状态管理终于重构完了，但回调逻辑呢？
他看了一眼代码，发现回调逻辑比想象的复杂 10 倍。
要不……先不改了？
小张的感悟：
“一开始以为‘发现问题 → 重构’很简单。”
“实际上，重构是一场持续的决策:改什么，不改什么，什么时候改。"
“不是所有问题都要立刻修，也不是所有重构都能完成。”
关键是：知道什么时候该停下来。
这篇文章就是要解决这个问题。
我们不追求“一次性大重构”，而是追求“渐进式改造”。
更重要的是：学会判断什么时候不该重构。