#001-文档驱动项目-为什么老项目需要文档驱动?

——当遗留代码遇上文档驱动开发

这篇文章的由来

之前我写了《用一份 .md,把想法变成产品》系列,讲的是怎么从 0 到 1 用文档驱动开发。文章发出后,收到很多反馈。其中最多的问题是:"这套方法挺好,但我们是老项目,代码都写了好几年了,还能用吗?"

有人更直接:**"新项目谁不会写文档?关键是屎山代码怎么办?"**这个问题很现实。大部分团队面对的不是"如何从零开始",而是"如何在已有的烂摊子上改进"。所以,这个系列就是来回答这个问题的。

一、遗留代码为什么这么难?

让我们先诚实地面对一个问题:为什么遗留代码这么难搞?

老项目更难,但更普遍

坦白说,老项目引入文档驱动比新项目难 10 倍。为什么?

**新项目是一张白纸:**你可以按理想状态设计,文档和代码同步推进。

**老项目是历史包袱:**代码已经写了,很多设计决策的人已经离职,文档要从头补。更难的是:没人知道该从哪里开始。

但老项目也有优势:**痛点更明显。**新人看不懂代码?知识流失严重?改个需求提心吊胆?这些痛点会成为推动力。

**新项目是一张白纸:**你可以按理想状态设计,文档和代码同步推进。

**老项目是历史包袱:**代码已经写了,很多设计决策的人已经离职,文档要从头补。更难的是:没人知道该从哪里开始。

但老项目也有优势:**痛点更明显。**新人看不懂代码?知识流失严重?改个需求提心吊胆?这些痛点会成为推动力。

所以,这个系列不讲理想状态,讲的是:如何在现实约束下,渐进式地引入文档驱动。

二、两种思路,两种结局

面对同一个老项目,不同的处理思路会带来完全不同的结果。让我们看两个真实的案例。

周五下午 5 点的噩梦

周五下午 5 点,你正准备关电脑下班。

产品经理突然出现在你工位旁:"这个支付功能能不能支持花呗分期?客户要得急,下周要上线。"

你心里一紧。

打开 IDE,找到 PaymentService.java,2000 行代码扑面而来。翻到支付核心逻辑,发现分散在 8 个文件里。上次改这块代码的同事 3 个月前离职了,留下的注释只有寥寥几行。

Git 历史显示,这个文件被 15 个人修改过,每次都是"临时补丁"。

你不知道:

为什么这里要用这个状态?
这个重试逻辑是处理什么场景的?
改了这里会不会影响其他支付方式?

这就是老项目的现状。

你可能会说:"这不就是技术债务吗?重构不就完了?"

但问题是:有多少项目有机会推倒重来?

大部分时候,我们只能在这堆"屎山"上继续搭积木。

不只是技术债务,是知识流失

老项目的问题,本质上不是代码写得烂,而是知识流失了。

什么知识?

1. 设计决策的知识

为什么选择这个方案而不是那个?
当初权衡了什么?
有哪些坑不能踩?

2. 业务规则的知识

这个特殊逻辑是处理什么场景的?
为什么这里要这样判断?
哪些是历史遗留,哪些是必须保留?

3. 隐藏依赖的知识

改了这里,哪些地方会受影响?
哪些是硬性约束,哪些可以调整?
有没有埋着的定时炸弹?

这些知识原本在老员工的脑子里。

但人会离职,记忆会衰退。

3 个月后,连写代码的人自己都忘了当初为什么这样写。

老项目的三大困境

困境一:知识孤岛效应

场景再现:

团队里有个"大神",负责支付模块 3 年了。

每次出问题,大家都找他。每次改需求,只有他敢动代码。

他成了团队的"单点故障"。

某天他离职了。

团队傻眼了:支付模块成了黑箱,没人敢动。新来的同事花了 3 周时间,才勉强理解核心流程。

有个数据很残酷:资深开发离职后,相关模块的维护效率会下降 60%。

这不是个例。

我见过一个团队,核心的异常重试逻辑只有一位离职员工完全理解。结果一次故障排查耗时 8 小时,因为没人知道重试次数为什么是 3 次,不是 2 次也不是 5 次。

答案最终在 Git 历史的某个 commit message 里找到:"限制为 3 次是因为更多次会占用过多线程资源"。

但这个知识,没有在任何文档里。

困境二:隐性复杂度累积

表面上看,支付流程很简单:

创建订单 → 调用支付 → 处理回调 → 更新状态 → 完成

但实际运行时,状态转换是这样的:

CREATED → PAYING → PAID → SUCCESS

但其实还有隐藏的路径:
PAYING → TIMEOUT → RETRYING → PAYING (最多 3 次)
PAID → REFUNDING → REFUND_FAILED → PAID (需要人工处理)
SUCCESS → CANCELLED (特殊情况下可以取消已完成的支付)

更要命的是,有些状态转换是隐式的:

// 你在代码里看到的
if (payment.getStatus() == PAID) {
    payment.setStatus(SUCCESS);
}

// 但在另一个文件的定时任务里
@Scheduled(cron = "0 */10 * * * ?")
public void reconcilePayments() {
    // 每 10 分钟检查一次
    // 如果支付超过 24 小时还是 PAID 状态,自动改为 CANCELLED
}

你改代码时,根本想不到有个定时任务在后台默默地改状态。

这就是隐性复杂度。

它不写在文档里,不体现在架构图里,只藏在代码的各个角落。

**真实成本:**一次"简单的"状态添加,引发了 3 个 bug,花了 2 周时间修复。

为什么?因为没人知道完整的状态转换路径。

困境三:团队越大,越慢

这听起来很反直觉:人多了,不应该更快吗?

但现实是:从 3 人团队扩展到 8 人,支付模块的需求交付周期从 1 周延长到 3 周。

为什么?

因为沟通成本超过了并行开发的收益。

3 个人的团队,大家对代码都很熟,改起来很快。

8 个人的团队,每次改动都要:

找到熟悉这块的人问清楚
评审时要多人对齐理解
测试时要考虑更多的交叉影响

结果就是:人多了,反而慢了。

根本原因:缺乏共同的知识基础。

每次都要重新对齐理解,每次都要从头解释一遍。

三、文档驱动的价值:从阅读理解到对话协作

现在让我们深入理解,为什么文档驱动能解决遗留代码的问题。

文档驱动能解决什么?不能解决什么?

说到这里,你可能会想:"那写文档不就行了?"

但并不是所有项目都适合文档驱动。

我得先给你泼盆冷水。

✅ 适合文档驱动的场景

1. 核心业务逻辑需要多人维护

如果一个模块只有你自己在维护,且不打算换人,那文档的价值有限。

但如果:

有新人要加入
需要跨团队协作
核心成员可能离职

那文档就是必需品。

2. 团队有人员流动

如果团队稳定,成员 3 年不变,靠口口相传也能维持。

但现实是:人员流动是常态。

平均来说,一个工程师在一家公司待 2-3 年。你的团队也不例外。

3. 需求变更频繁但模式相似

支付模块就是典型:

新增支付方式(支付宝、微信、花呗...)
调整支付流程(加验证、改状态)
处理新的异常场景

如果每次都从头梳理,太浪费时间。

有文档,新需求来了,对照着改就行。

4. 有明确的业务规则和状态机

像支付、订单、工单这种,业务规则很明确,用文档描述很清晰。

但如果是算法类、探索性的项目,文档的价值就打折扣了。

5. 团队愿意投入时间建立长期能力

这一条最重要。

如果团队连看文档的时间都没有,写了也白写。

如果管理层只看短期收益,不愿意投入,那趁早别开始。

❌ 不适合的场景

1. 一次性项目或短期项目(< 3 个月)

投入产出比不划算。

写文档的时间,可能比项目本身还长。

2. 团队规模很小(1-2 人)且稳定

面对面沟通更高效。

文档反而成了负担。

3. 业务逻辑极其简单

纯 CRUD 的管理后台,代码本身就是最好的文档。

4. 代码即将重写

如果已经决定推倒重来,别在旧系统上浪费时间了。

先重写,再为新系统写文档。

5. 团队文化强烈抵制文档

如果团队里全是"代码就是文档"的信仰者,且无法改变,那就别强推了。

等待合适的时机,或者接受现状。

6. 管理层不支持持续投入

文档需要长期维护。

如果管理层只给你 3 个月时间"见效果",那注定失败。

真实收益:不是万能药

文档驱动不是银弹,但在合适的场景下,收益是实实在在的。

短期收益(1-3 个月)

别指望立竿见影,但会有一些早期信号:

新人 onboarding 时间减少 50%

从 2 周缩短到 1 周
新人反馈:"有文档看懂多了"
但前提是文档质量过关

Code Review 效率提升 30%

有文档作为讨论基础
减少"这里为什么这样写"的反复解释
但需要团队养成参考文档的习惯

需求澄清时间减少 40%

文档作为沟通起点
减少重复的需求对齐
但需要文档及时更新

但是:

需要额外投入 20-30% 的时间编写文档
前期效率可能暂时下降 10-20%
团队需要适应新的工作方式

中期收益(3-6 个月)

如果坚持下来,会看到更明显的改善:

需求开发周期缩短 20-30%

设计阶段就能发现问题
减少返工和 bug
团队协作更顺畅

Bug 率下降 25%

早期发现设计问题
避免隐藏的状态转换 bug
测试覆盖更全面

技术方案评审时间减少 50%

基于文档讨论,更高效
减少"我以为你以为"的误解

但是:

文档维护成本趋于稳定(每周 2-4 小时)
部分成员可能仍有抵触
需要持续推动和优化

长期收益(6-12 个月)

真正的价值在长期:

知识沉淀效应

团队整体能力提升
不再依赖个别"大神"
新人能更快独立工作

维护成本持续下降

改代码前先看文档
减少"摸黑改代码"的风险
问题排查更快

支持更复杂的需求变更

对系统理解更深
敢于做大的重构
技术债务可控

形成团队文化

新成员自然遵循
文档成为工作方式的一部分
影响其他团队

真实成本:没人告诉你的那些

网上的文章都在说文档的好处,但很少有人诚实地谈成本。

我来说说。

初期成本(前 3 个月)

时间投入:每周 8-12 小时(团队总计)

这不是一个小数字。

对于一个 5 人团队,相当于 15-25% 的工作时间。

具体花在哪里?

编写初始文档:20-40 小时
团队培训和对齐:8-16 小时
建立流程和模板:8-16 小时

学习成本:每人 4-8 小时

学习文档工具和方法
适应新的工作流程
需要 2-4 周才能自然

机会成本:可能延缓 1-2 个需求交付

这是最容易被忽视的。

前期团队要分心搞文档,开发速度会下降 10-20%。

如果正赶上紧急需求,可能得延期。

持续成本(3 个月后)

维护成本:每周 2-4 小时

文档更新:1-2 小时
Code Review 中检查文档:1 小时
定期回顾和改进:1 小时(每月)

隐性成本:

需要有人推动和维护(通常是 Tech Lead)
可能引发团队文化冲突
文档质量参差不齐需要持续改进

心理成本

这个最难量化,但很真实。

推动者的压力:

要说服团队
要应对抵触情绪
要向管理层证明价值
看不到立即效果时的焦虑

团队成员的适应压力:

改变习惯的不适
"又要写文档"的抵触
担心被批评文档写得不好

总成本估算

对于一个 10 人团队,第一年的总成本:

直接成本:

100-150 小时/人/年 = 1000-1500 小时
按平均时薪 200 元算:20-30 万元

工具成本:

文档工具(Wiki、Confluence 等):5-10 万元/年
自动化工具(Swagger、Screw 等):开源免费或少量成本

机会成本:

延缓 1-2 个需求:难以精确估算,但也是实实在在的成本

总计:约 20-30 万元的时间成本 + 工具成本

收益何时能覆盖成本?

乐观估计:6-9 个月

团队配合好
文档质量高
业务相对稳定

现实估计:12-18 个月

有些波折和调整
需要持续优化
逐步看到复利效应

如果 18 个月后仍未见明显收益,应考虑调整策略或停止。

这不是失败,只是这个方法可能不适合你的团队。

失败案例:为什么很多团队放弃了?

说了这么多好处,我得诚实地告诉你:很多团队尝试文档驱动,最后都放弃了。

为什么?

案例一:文档变成形式主义

背景:

某团队决定推行文档驱动,强制要求所有代码提交都要更新文档。

听起来很严格,很好。

问题:

文档模板过于复杂,填写一份需要 30 分钟。

大家开始应付:

复制粘贴之前的文档
随便写几句应付检查
没有人认真看文档

6 个月后,文档和代码严重脱节。

大家宁愿读代码,也不看文档。

教训:

过度的流程会扼杀主动性。

文档应该是帮助理解的工具,不是完成任务的负担。

正确做法:

从最小可行文档(MVD)开始:

只记录核心决策和关键流程
模板要简单,填写时间 < 10 分钟
不追求 100% 覆盖,聚焦高价值内容

案例二:AI 生成的文档无人维护

背景:

某团队用 AI 工具快速生成了 100 篇文档。

看起来效率很高。

问题:

AI 生成的文档过于泛化:

缺乏项目特定的业务上下文
设计决策和"为什么"都是编的
开发人员不信任这些内容

更糟糕的是,没有人有 ownership。

文档很快过时,但没人愿意维护。

教训:

AI 是工具不是银弹。

人的 ownership 和理解才是关键。

正确做法:

AI 辅助生成初稿,人工精炼和维护核心部分:

AI 生成框架和结构
人工补充业务规则和设计决策
明确每份文档的 Owner
定期 Review 和更新

案例三:文档成为新的技术债务

背景:

某团队建立了详尽的文档体系,覆盖了所有模块。

看起来很完美。

问题:

文档量太大(200+ 页):

无人完整阅读
文档之间有冲突和重复
维护成本超过收益

3 年后,60% 的文档已经过时。

团队决定"推倒重来",但没有人愿意去清理。

文档变成了新的技术债务。

教训:

文档也需要"重构",要敢于删除过时内容。

不是越多越好,而是越精准越好。

正确做法:

遵循"最少文档原则":

只记录真正需要的内容
定期清理过时文档(每季度一次)
文档要有生命周期管理
敢于删除低价值内容

自我评估:你的项目适合文档驱动吗?

说了这么多,关键问题来了:你的项目适合吗?

别急着开始,先做个评估。

评估检查表

项目特征评估:

项目已运行 > 6 个月,且预期继续运行 > 12 个月
代码库规模 > 10,000 行或核心模块 > 3,000 行
团队规模 ≥ 3 人,或有人员流动计划
有明确的业务逻辑,不只是 CRUD
需求变更频率 ≥ 每月 1 次

团队准备度评估:

Tech Lead 愿意投入时间推动
至少 1-2 名核心成员支持
管理层认可长期投入价值
团队成员有基本的文档编写能力
没有强烈的抵触情绪

资源可行性评估:

可以分配 20-30% 的时间用于文档建设(前 3 个月)
允许前期效率暂时下降 10-20%
有持续改进的耐心(至少 6 个月)
可以接受失败和调整

评分标准

12-16 项:非常适合,现在就可以开始

你的项目和团队条件都很好。

但仍要保持理性,做好长期准备。

8-11 项:适合,但需要先解决部分阻碍因素

找出那些未勾选的项,先想办法改善。

比如:

管理层不支持 → 先做小范围试点,用数据说话
团队有抵触 → 先找支持的人,展示成功案例

4-7 项:不太适合,建议先从小范围试点

不要全面推广。

选一个小模块试试水,看看效果如何。

如果 3 个月后效果不好,及时停止。

0-3 项:不适合,应该寻找其他改进方案

诚实地说,你的项目可能不需要文档驱动。

或者说,现在不是合适的时机。

可以考虑其他方案:

加强代码注释
定期技术分享
Pair Programming
等待更好的时机

成本收益计算器

别只看概念,算算实际的投入产出。

投入估算(前 6 个月):

初期投入(前 3 个月):
- 核心文档编写:40 小时 × 时薪 200 元 = 8,000 元
- 团队培训:16 小时 × 5 人 × 200 元 = 16,000 元
- 流程建立:16 小时 × 200 元 = 3,200 元
- 机会成本(延迟需求):1 个需求 × 20,000 元 = 20,000 元

持续投入(3-6 个月):
- 文档维护:2 小时/周 × 12 周 × 200 元 = 4,800 元
- Review 和改进:1 小时/周 × 12 周 × 200 元 = 2,400 元

总投入:54,400 元

收益估算(6 个月后):

效率提升:
- 新人 onboarding 节省:1 周 × 1 人 × 8,000 元 = 8,000 元
- 需求开发加速:20% × 5 个需求 × 20,000 元 = 20,000 元
- Bug 减少:25% × 历史 bug 成本 10,000 元 = 2,500 元

风险降低:
- 避免知识丢失损失:预估 20,000 元
- 减少沟通成本:30% × 会议时间 × 5,000 元 = 1,500 元

总收益:52,000 元

ROI = (总收益 - 总投入) / 总投入 = -4.4%

第一个 6 个月,ROI 是负的。

这很正常。

但如果坚持到 12 个月,收益会持续累积,ROI 会变正。

如果 ROI > 0.5(6 个月内回本),则强烈建议引入。