——写完只是开始，维护才是关键
系列导读：这是《老项目如何引入文档驱动》系列的第 4 篇。前三篇我们聊了为什么需要文档驱动、如何用 AI 理解代码、如何写出第一份 MVD。现在，更大的挑战来了——如何让文档不过时？如何让它持续有价值？
小李的困境：文档成了“坑”
小李是我们团队的后端工程师。
3 个月前，他写了一份支付回调的 MVD，记录了核心流程和关键决策。
当时大家都说好：
“太棒了！终于有文档了！”
“新人 onboarding 时间从 3 天缩短到半天！”
但 3 个月后……
小王是新来的实习生，拿着小李的文档准备改一个支付超时的 bug。
文档上写：“超时重试 3 次，间隔 5 秒。”
小王照着文档改完代码，提交上线。
结果呢？
生产环境出问题了。
用户投诉疯了：“支付失败，但钱被扣了！”
小李紧急回滚，排查后发现：
文档已经过时了。
2 个月前，产品经理要求把重试间隔改成 10 秒，开发改了代码，但没人更新文档。
小王按照过时的文档改 bug，导致逻辑错误。
小李崩溃了：
“我当初花了 6 个小时写这份文档，现在它反而成了‘坑’！”
“以后谁还敢相信文档？”
这就是很多团队遇到的困境：文档写完了，但没人维护，最后变成了新的技术债务。
你可能会说：“那就每次改代码都更新文档不就行了？”
但问题是：
-
什么时候该更新文档？每次小改动都要更新吗？
-
谁来更新？改代码的人，还是专门的文档负责人？
-
怎么保证更新不遗漏？
-
如何在“快速迭代”和“文档维护”之间平衡？
这就是这篇文章要解决的问题。
我们不追求“完美同步”的文档，而是追求“可持续维护”的文档。
为什么文档会过时？三个根本原因
在聊解决方案之前，我们先看看文档为什么会过时。
1. 没有明确的更新时机
场景：
开发改了一行配置，心想：“这么小的改动，应该不用更新文档吧？”
结果 10 个小改动累积下来，文档和代码完全对不上了。
核心问题：
团队没有共识——什么程度的变更需要更新文档？
2. 更新责任不清晰
场景：
-
开发说：“我只负责写代码，文档应该让技术写作团队更新。”
-
技术写作说：“我们不懂具体逻辑，应该让开发更新。”
-
产品说：“这是技术的事，我不管。”
结果就是：谁都不管。
核心问题：
没有明确谁对文档负责。
3. 缺乏反馈机制
场景：
文档过时了，但没人知道。
直到新人踩坑，或者生产事故，才发现文档早就失效了。
核心问题：
没有机制来发现文档已经过时。
所以，可持续的文档维护，需要解决这三个问题：
-
什么时候更新？（触发时机）
-
谁来更新？（责任人）
-
怎么发现过时？（反馈机制）