敏捷开发不是无文档，而是适时文档

一、先给你看一个真实的悲剧

2018 年，我接手过一个已经在线上跑了 3 年的电商中台项目。当时团队换了三拨人，核心开发只剩一个入职不到半年的小伙。有一天他找我，声音都在抖：“哥，订单状态机里有一个叫 PARTIAL_REFUND_LOCKED 的状态，代码里有，数据库里也有，但是没有一个人知道它是干什么用的。现在财务要结算，有几万条订单卡在这个状态，我不敢动。”

我们翻遍了 Confluence，只找到一份 2016 年的系统设计文档。打开一看，目录很漂亮，从架构图到部署方案一应俱全，唯独关于订单状态机的部分只写了一句话：“详细逻辑见代码注释”。去翻代码注释，注释写的是：“TODO：待补充状态说明”。

这就是典型的“要么拼命写，要么什么都不写”带来的后果。项目初期为了过 CMMI 评审，产出了一百多页没人看的文档。等到真正需要一份能救命的状态机说明时，它恰好是空的。

这件事让我彻底想明白一个问题：敏捷开发从来不是反对文档，它是反对把文档当成一次性交付物来生产。问题出在“什么时候写、写给谁看、写到什么程度”，而不是“要不要写”。

二、核心结论：文档是负债还是资产，取决于一个变量

我先把这个结论放在最前面：

在敏捷开发中，文档的本质是一种“信息库存”。库存太多占用资金（时间），库存太少导致停工待料（返工、事故）。敏捷的做法不是清空仓库，而是改成 JIT（准时制生产）模式，在需要的时候，刚好有够用的信息。

这个判断不是教科书上抄来的。过去十年，我以研发负责人和咨询顾问的身份服务过 40 人、120 人、400 人三种规模的组织。一个反复出现的规律是：团队规模一旦跨过 80-100 人，或者系统运行超过 18 个月，没有“适时文档”的代价就会非线性增长。

PingCode 的客户案例库里有一个数据我非常认可。他们服务的一家金融科技公司（约 150 人研发团队）在实施敏捷之初做了一次内部调查，结果发现：

• 47% 的开发时间消耗在理解现有代码逻辑上，而不是写新功能。
• 63% 的线上事故直接或间接与“信息不对称”有关，改了 A 模块不知道会影响 B 模块。
• 每次团队扩容 10%，平均有 1.8 个需求因为“不知道以前做过类似功能”而被重复开发。

这些数字的背后都是一个原因：知识被锁在少数人的脑子里，而脑子是会离职的。

三、为什么行业会有“敏捷=无文档”的错误共识

这个误解的源头是可以追溯的。2001 年敏捷宣言里有一句：“可工作的软件 胜过 面面俱到的文档”。很多人只看到了“胜过”两个字，自动把前半句翻译成“文档不重要”。但实际上，这 17 位滑雪胜地出来的老炮说的是另一层意思：文档的优先级要让位于可工作的软件，而不是文档要被消灭。

后来这个误解被层层放大，主要有三个推手：

1. 把“过度文档”的痛当成“任何文档”的错

在 2000 年代初期，以 RUP（Rational Unified Process）为代表的重型流程把文档推到了极致。我 2009 年参与过一个通信行业的项目，需求规格说明书写了 9 个月，等评审通过时，运营商的技术规范已经升级了。这种痛是真实的，但解决方案不应该是从 100 页砍到 0 页，而是砍到刚好够用的 8 页。

2. Scrum 认证培训的简化传播

我上过三家不同机构的 CSM 课程，没有一位培训师会明确说“不要写文档”。但课程里大量强调“用户故事卡片上的对话比文档重要”，加上时间限制，很难展开讨论文档的边界问题。学员回到团队后，最容易执行的就是“先别写文档了”，因为写文档确实痛苦。

3. “代码即文档”的理想主义

“代码就是最好的文档”这句话，是写给机器看的，不是写给人看的。代码能精确回答“怎么做”（How），但很难回答“为什么这么做”（Why）和“什么情况下不能这么做”（When Not）。当一段代码背后是一个纠结了三个月的业务妥协时，没有文字记录，后来者只能看到结果，看不到约束条件。改一行，全盘崩。

四、什么才是真正的“适时文档”

我先给出一个可操作的定义：

适时文档，是指在信息损失即将超过可接受阈值时，用最低成本的结构化方式，把关键决策、边界条件和接口契约固化为团队可检索的资产。

拆开来看有四个关键条件：

1. 触发时机：不是按日历触发，而是按风险触发

很多团队会在 Sprint 最后一天留两小时“补文档”，这是最糟糕的做法。文档的触发条件应该是：

• 知识集中度过高：某个模块只有一个人懂，这时候哪怕只写一页纸的“关键逻辑地图”，价值也远超 null。
• 跨团队接口确定：一旦两个团队的边界定下来，接口契约必须落成文字。口头约定在第三个人加入时就开始失真。
• 非显而易见的决策：如果评审会上有人说“这个方案反直觉，但必须这么做”，必须当场记录原因。

2. 最低成本：宁可简陋，不可没有

“最低成本”这四个字很多人理解错了。他们觉得“我可以写得很详细，只是现在没时间”。不，“最低成本”是指：在有限的格式里，你只被允许写最重要的那几件事。我在团队里推行过一个方法叫“一页纸架构决策记录”，格式固定到只有五个字段，不给任何人展开写的机会。

3. 结构化：方便机器索引，也方便人脑扫描

散落在飞书群、Slack 频道和钉钉已读未读里的信息不是文档，是聊天记录。三个月后搜索关键词，出来 200 条消息，没有人会逐条翻。结构化意味着：有固定存放位置、有固定命名规则、有固定元数据（作者、日期、关联模块、状态）。

4. 可检索：找不到等于不存在

有一次我在客户现场问团队：“你们的接口文档在哪？”回答是：“在 XXX 的共享目录里，我发你链接。”这种文档对团队来说就是不存在。可检索意味着：新成员用他知道的唯一关键词（比如一个接口名或一个业务名词）能在 30 秒内找到目标文档。

五、必须打掉的四个文档误区

1. “用户故事就是文档”

用户故事是需求的占位符，不是文档。故事卡片上写“作为一个买家，我希望在退款时看到进度，以便有预期”，这句话对开发来说几乎没有任何可执行的信息。真正的文档是出现在这个故事被拆分、评审之后产出的验收标准、状态流转图和异常处理清单。故事只是目录，不是内容。

2. “写了文档就得一直维护，所以干脆不写”

这是一个典型的“全或无”思维陷阱。文档有不同的生命周期要求：

• 接口契约必须实时维护，因为下游依赖它。
• 架构决策记录一旦写成，永不修改，只追加新决策。
• 模块概览每季度花 30 分钟更新一次即可，只改变化的部分。

在 PingCode 的实践里，他们把技术文档和代码仓库的 MR（Merge Request）做了关联。当一段代码因为文档过时导致 CR 被打回时，系统会自动标记该文档为“待验证”。维护文档的工作量被拆成了每次 CR 时的 2 分钟检查，而不是一个季度一次的半天集中攻坚。

3. “新人加入时有老员工带就行”

我在 120 人团队时做过一个统计：把一个毕业生培养到能独立处理生产事故的水平，纯靠老员工口传心授需要 4.5 个月。如果有一套结构化的模块说明文档作为辅助，这个时间缩短到 2.8 个月。差距不是因为老员工不教，而是因为老员工的知识在传递时是碎片化、故事化的，新人需要在脑中花大量时间拼图。一份好的文档就是那张拼图的封面图。

4. “我们用了 TDD，测试用例就是文档”

测试用例是极好的可执行规范，但它只能回答“系统在什么输入下应该有什么输出”。它回答不了：为什么选了 gRPC 而不是 REST？为什么这个字段允许为空但在下游不允许？为什么这个 DDL 时间定在凌晨 3 点而不是业务低峰期？测试用例覆盖了 What，覆盖不了 Why。

六、适时文档的四层实践框架

这套框架是我在过去五年里，从三个不同规模团队的实际运作中提炼出来的。它的核心不是告诉你“写什么”，而是帮你建立一个决策机制：“在什么情况下，不写文档的代价会超过写文档的成本”。

1. 第一层：接口契约，必须实时维护，不容妥协

接口是团队之间、系统之间的边界。一旦边界模糊，所有上下游都会开始做“防御性假设”，A 团队假设 B 团队会做校验，B 团队假设 A 团队已经处理了。最后的结果是：没人在做校验，但每个人都觉得有人在负责。

接口契约至少包含：

• 字段的必填性、类型、长度限制
• 幂等性保证方式
• 错误码和对应的调用方处理建议
• 版本兼容策略

一个实用的原则：如果一个接口被两个以上消费者调用，它的文档必须和代码同步提交。做不到同步，就在 PR 模板里加一个 checkbox：“该变更是否涉及对外接口？如是，请附上文档更新链接”。

2. 第二层：架构决策记录，只写一次，永不修改

ADR（Architecture Decision Record）是我见过投资回报率最高的文档形式。每一条记录不超过一页 A4 纸，格式固定：

• 背景：我们面临什么问题？
• 决策：我们选择了什么方案？
• 后果：这个选择带来了哪些正面和负面影响？
• 被淘汰的方案：我们考虑过什么？为什么不选？

2021 年我在一个支付系统的重建项目中推行了 ADR。项目期间一共积累了 47 条决策记录。一年后团队核心成员离职了 60%，新团队接手后，靠着这 47 条 ADR 在两个月内完成了平稳过渡。没有一条 ADR 需要修改，因为历史决策不需要修改，只需要被新的决策覆盖。

3. 第三层：模块概览，定期刷新，保持温度

模块概览是给“第一次接触这个模块的人”看的。它不需要详尽无遗，但必须能帮人在 15 分钟内建立起对这个模块的核心认知。我推荐一个固定的六段式结构：

1. 本模块解决什么问题（一段话，不超过 100 字）
2. 核心数据模型（一张简化的 ER 图或关键表说明）
3. 关键流程（用序号描述 3-5 个核心步骤）
4. 对外接口说明（链接到接口契约文档）
5. 已知风险和技术债（诚实写出来，这比掩盖更有价值）
6. 维护人（至少两个人的名字，避免单点）

维护频率：每个季度一次，每次不超过 30 分钟。如果模块在一个季度内没有任何变更，就在文档底部更新一行“最近检查日期”，证明这份文档还是“活着”的。

4. 第四层：操作手册，按场景组织，不是按功能菜单

这是最容易过度编写，也最容易在关键时刻救命的文档。大部分运维手册写得像产品说明书，“点击 A 按钮，进入 B 页面，选择 C 选项”，这种写法在紧急故障时毫无用处。

好的操作手册应该按场景组织：

• “如果订单量突然下降 50%，你应该看哪 3 个监控面板？”
• “如果数据库连接池满了，紧急止血的 3 个步骤是什么？”
• “如果需要回滚最近一次发布，具体命令和参数是什么？”

2020 年双十一期间，我所在的一个电商团队凌晨 1 点 23 分收到系统报警。值班的是一个入职两个月的新人。他按照操作手册里的“支付回调延迟处理”场景，在 4 分钟内完成了紧急降级操作。这份手册一共只有 12 个场景，每个场景不超过一屏。

七、一套可量化的文档决策模型

很多团队卡在“这个要不要写文档”的纠结里，反复拉锯。我建了一个极其简单的快速评估矩阵，能帮助团队在 10 秒内做出选择：

这五个维度中，只要有两个落在“高风险信号”，就必须产出对应的文档。不需要所有维度都满足才写，那会让决策标准变得过高而形同虚设。

八、PingCode 服务 100 人以上组织时看到的文档规律

PingCode 的核心客户群是 100-500 人规模的研发组织。我在研究他们的案例和与他们的解决方案团队交流时，发现了一些跨越行业的共同规律：

1. 100 人是一个“信息断裂带”

当研发团队在 50-80 人时，靠周会、站立晨会和群聊基本能保持信息同步。一旦超过 100 人，你不再认识每一个写代码的人。一个人对另一个团队的代码完全没有个人情感上的“背书信任”，这时候唯一能信任的就是文档。

PingCode 服务的一家新能源车企的研发中心，从 70 人扩张到 160 人只用了 8 个月。CTO 回忆说：“前 6 个月我们还在吃老本，老人知道一切。第 7 个月开始，新人提的问题老人也答不上来了，因为系统已经被改了太多地方，没人能看清全貌。”他们被迫停下来花了两个月做了一次彻底的“知识结构化”，才重新把交付速度拉回正轨。

2. 文档需求不是线性的，是跳跃的

并不是 200 人的团队比 100 人的团队需要多一倍的文档。真实情况是：文档需求在特定节点上急剧跳跃。这些节点包括：

• 团队首次拆分（从一个大组拆成两个以上特性团队）
• 引入第三方外包或远程协作团队
• 核心系统进入“维护期”而原始团队已经转向新项目
• 发生了一次影响用户/营收的重大线上事故

在这些节点上，文档的价值会急剧上升，而在此之前它可能确实显得“可有可无”。

3. 文档的形式比内容更容易成为卡点

很多团队在“用什么工具写文档”上争吵的时间，比真正写文档的时间还长。用 Confluence？用 Notion？用飞书文档？用 Git 仓库里的 Markdown？

PingCode 的做法值得借鉴：文档的存放位置取决于它的消费场景，而不是写作者的偏好。与代码强关联的技术文档（ADR、接口说明、模块 README）直接放在代码仓库，跟随分支走。与项目管理和需求强关联的文档（需求说明、验收标准、发布计划）放在项目管理工具里，与对应的需求工作项绑定。开发不用在代码和文档工具之间频繁切换，产品经理也不用去 Git 仓库里翻 Markdown。

九、具体行动指南：三种规模的团队分别怎么做

1. 15 人以下的小团队：维护一张“团队知识地图”

这个规模不需要任何重型文档体系。但有一件事要做：画一张模块-负责人映射表，放在每个人都能看到的地方。格式不限，但要能回答：“如果想了解 XX 模块的实现逻辑，应该找谁聊？”这张表的价值不在于“找人”，而在于暴露风险，当某个模块只挂了一个人的名字时，你就知道那里有一颗定时炸弹。

此外，强制一个习惯：任何超过 30 分钟的结对编程或方案讨论，结束后花 5 分钟在代码仓库 wiki 里留一段总结。不是给外人看，是给一个月后的自己看。

2. 15 到 80 人的成长团队：建立 ADR 和接口契约的双轨制

这个阶段是建设文档习惯的黄金窗口期。团队还没有大到失控，但已经开始感受到“不知道隔壁在做什么”的痛。我的建议是：

• ADR 先行：在代码仓库里建立一个 /docs/adr 目录。从下一个 Sprint 开始，任何一个被反复讨论的技术选型，必须产出一条 ADR 才能合并代码。
• 接口文档自动生成：对于 RESTful 或 gRPC 接口，从代码注解直接生成文档页面。不要手动维护接口说明，那一定会过期。工具链用 Swagger、GraphQL Schema 都可以。
• 给文档写作者正向反馈：在回顾会上，如果有人因为一份文档受益（比如避免了一次事故、加快了 onboarding），大声说出来。文档文化的核心不是惩罚没写的人，而是奖励写了的人。

3. 100 人以上的大型组织：建立“信息架构师”角色

这个规模下，文档不是一个技术问题，是一个信息架构问题。一个接口文档写得再完美，如果放在了一个错误的目录下，对新员工来说就是不存在。信息架构需要有人专职负责，不一定是全职岗位，但必须有人被明确授权来回答以下问题：

• “关于 XX 系统的信息，我的第一入口在哪里？”
• “这份文档是当前有效的唯一信源，还是另有其他地方已经更新过？”
• “为什么找不到关于 XX 模块的任何文档，它是真的没写还是放在了我不知道的地方？”

在 PingCode 服务的一家 300 人规模的 SaaS 企业里，他们设置了一个“技术知识官”的轮值角色。每个季度换一个人，职责包括：检查核心文档的时效性、删除过期的内容、在全员会上汇报当前知识管理的健康度。这个角色不需要自己写文档，他像一个园丁，负责修剪和浇水。

十、如何判断你的团队在文档上走偏了

我列一个自检清单，这些信号出现任意三个，就说明你的文档策略需要调整：

1. 看文档的人不是因为想看，而是因为流程强制要求。如果一份文档的唯一读者是 PMO 或质量保证人员，它很可能是多余文档。
2. 同一个问题在不同的文档里给出了矛盾的答案。这比没有文档更糟糕，因为它制造了错误的确定性。
3. 当发生线上事故时，团队的第一反应是翻群聊而不是翻文档。这说明文档已经失去了“信源”的地位。
4. Code Review 时经常出现“这里和文档描述不一致”的评论。文档维护已经跟不上代码节奏，需要缩小文档范围或自动化生成。
5. 新人入职第一周完全没接触过团队文档，全靠结对编程。结对编程是极好的知识传递方式，但它应该和文档互补，而不是替代。
6. 写文档被当成一种“不务正业”的行为，会被 leader 提醒“先把代码写完”。这种文化信号一旦出现，适时文档就不可能建立起来。

十一、我的底线判断：三种文档绝对不能砍

在做了无数次的权衡和妥协之后，我给自己定了一个不可退让的底线。无论团队再敏捷、周期再短、业务再急，以下三种文档必须存在：

1. 系统间交互的接口契约

原因不用再展开。只强调一点：任何跨团队的接口变更，如果没有文档记录，就等同于在没有医嘱的情况下给系统做器官移植。

2. 数据模型的字段含义说明

我见过最贵的一行注释缺失，是一个叫 “type” 的字段。它有三个取值：1、2、3。没有注释。三个取值分别对应三种完全不同的业务路径。原开发者离职后，接手的人以为 3 是 2 的升级版，结果导致了一笔六位数的资金计算错误。对字段含义的说明，是写给未来那个凌晨三点被报警叫醒的人看的。

3. 非显而易见的业务规则

什么是“非显而易见”？一个判断标准：如果你把这个规则讲给一个刚入职三天的开发听，他会问“为什么？”，那么这条规则就是非显而易见的。例如：“退款金额不能直接从订单总金额扣除，必须先经过风控系统的二次计算，即使风控系统返回的金额和订单总金额相同。”这种规则如果没有文档，后来者大概率会“优化”掉这一步，因为从代码逻辑上看它是多余的。

十二、写在最后：文档不是写给现在的你看的

十年前，我是一个典型的“代码至上主义者”。我觉得写好注释、写好测试用例就够了，其他的文档都是在浪费我写代码的时间。直到我自己成了那个凌晨三点翻看自己三年前写的代码却完全想不起当时为什么要那么写的人。

文档不是写给现在的你看的，是写给未来那个已经忘记了所有上下文、但必须快速做出正确判断的你看的。

敏捷开发追求的是快速响应变化，但“响应”的前提是“理解”。没有适时文档，你面对的不是变化，是迷雾，你不知道当前的系统处于什么状态，不知道过去的决策埋下了哪些约束，不知道改动边界在哪里。在这种情况下，任何“快速响应”都是赌博。

所以，如果你只能从这篇文章里带走一句话，我希望是：

别在文档上追求“写得全”，追求“写得准”。不要问“我们要不要写文档”，要问“如果这件事只有一个人知道，而这个人明天就不在了，会出多大的事”。答案就在那个问题的严重程度里。

从现在开始，回到你的团队，翻开你们最核心那个模块的文档目录。如果它是空的，或者里面最新的文档是两年前的，先花 30 分钟写一份“非显而易见规则清单”。不需要排版，不需要文采，只需要把那些“不写下来就一定会被忘掉”的东西倒出来。这就是适时文档的真正起点。