瀑布开发不是文档堆砌，是决策记录

一、先说结论：瀑布文档的最大悲剧，不是写太多，而是写完了没人知道那是决策

去年我给一个做银行核心系统的团队做咨询，他们一个项目经理翻出一份三年前的需求规格说明书，问我："老师你看，当年我们写了800多页，现在系统要迁移，这些文档还有什么用？"

我翻到第三章，找到一条关于"利率计算精度"的记录。上面写着："计息方式采用按日计息，保留小数点后8位。"就这一句话，没有前因后果，没有讨论过程，没有为什么是8位而不是6位或10位的说明。我问他："你知道当年为什么定8位吗？"他摇头。"如果新系统要用6位，你知道风险在哪吗？"他还是摇头。

这就是问题的核心：那800页文档不是太少，而是缺少了最关键的东西，决策背景。它们记录了"是什么"，但没有记录"为什么是这样的"。它们像一本没有判决理由的判决书，只告诉你结果，不告诉你法理。三年后，时过境迁，当初拍板的人可能早已离职，留给后人的只是一堆来路不明的技术指令。

所以我要在这个开头就直接抛出我的核心判断：瀑布开发的价值从来不在于它产出了多少文档，而在于它是否产出了高质量的决策记录。如果文档只是需求的堆砌、设计的流水账、测试用例的罗列，那确实没什么用，敏捷的支持者们骂得对。但如果文档记录的是团队在每个关键节点上"为什么这么选、放弃了什么、承担了什么风险"，那它就是整个组织最宝贵的工程资产。

我在过去七年里参与过二十多个大型项目的交付或审计，有政府财政系统的，有商业银行信贷系统的，有制造业ERP的。一个反复出现的规律是：文档写得厚的项目不一定成功，但文档里找不到决策痕迹的项目，一定会在某个时间点付出惨痛代价。这个代价可能是重复踩坑，可能是核心人员离职后系统无人能改，可能是甲乙双方对需求理解出现分歧后无法仲裁。

下面我会系统拆解这个问题，从"文档堆砌"和"决策记录"的本质区别讲起，到具体怎么写出能穿越时间的决策文档，再到什么情况下你需要坚持瀑布的文档纪律，什么情况下可以放松。

二、文档堆砌和决策记录，表面都是字，底层逻辑完全不同

先讲一个我亲身经历的对比案例。

2018年我在一个政务云项目上做架构评审，他们的需求文档有整整1200页。我随机抽了三章去看，发现一个有趣的现象：关于"用户登录"这个功能，文档写了12页，包括界面原型、字段说明、校验规则、错误提示文案，详细到不能再详细。但关于"为什么选择OAuth2.0而不是SAML作为统一认证协议"这个关键架构决策，全文只出现了一句话："系统采用OAuth2.0协议实现单点登录。"

我当场问架构师："当时为什么选OAuth2.0？"他的回答让我印象深刻："因为大家都用这个。"

这就是典型的"文档堆砌"思维：在执行层面事无巨细，在决策层面一笔带过。它背后的假设是：只要我把该写的都写了，文档就算完成了。但文档的真正读者不是当下的开发人员，而是半年后接手维护的工程师、两年后做系统升级的架构师、三年后做审计的合规官。他们需要知道的恰恰不是"界面有几个按钮"，而是"当初为什么这么设计"。

1. 文档堆砌的四个典型特征

根据我对超过50个项目文档的审计经验，文档堆砌通常具有以下特征：

第一，只见树木不见森林。细节极其丰富，但缺乏上下文。比如详细描述了某个接口的参数格式，但没有说明这个接口在整个业务链路中的定位，以及为什么需要这个接口。

第二，只记录结论不记录推导过程。需求文档里写满了"系统应支持XX功能"，但没有任何关于优先级排序、业务价值评估、替代方案分析的内容。这导致后来者在面对需求变更时，无法判断哪些约束是可以松动的，哪些是底线。

第三，文档之间缺少关联。需求文档、设计文档、测试用例各自独立，互相引用极少。当需求变更时，你无法快速定位哪些设计模块和测试用例需要同步更新。

第四，缺少责任人和时间锚点。很多文档只在封面上有一个日期和作者，但在具体的条目级决策上没有记录"谁在什么时候基于什么信息做出了这个判断"。三年后你想找个人问，连找谁都不知道。

2. 决策记录的本质：把隐性知识显性化

我们做一个思想实验。假设你的团队里最资深的架构师明天离职，他脑子里关于系统设计的所有判断和权衡，哪些已经落在了文档里？哪些会随着他一起离开？

决策记录的核心理念是：任何一个可能影响系统长期演进的关键判断，都必须包含以下四个要素，我称之为"决策四元组"：

• 背景：我们在什么时间点、面临什么业务或技术约束下做这个决策？
• 方案对比：我们考虑过哪些替代方案？各自的优缺点是什么？
• 决策理由：为什么最终选择了A而不是B？核心考量因素是什么？
• 已知风险与接受度：我们知道这个方案有什么不足或风险，为什么仍然接受它？

举个例子。同样是"系统采用OAuth2.0协议"，一份决策记录级别的文档会这样写：

"2020年3月，统一认证方案选型。备选方案包括SAML 2.0、OAuth2.0和自研Token方案。SAML在政府体系内应用广泛，但我们的业务场景涉及大量移动端接入，SAML对移动端支持较弱；自研方案灵活但后续对接外部系统成本高。考虑到未来三年内需要对接至少6个外部政务平台，且这些平台均支持OAuth2.0，团队决定采用OAuth2.0。已知风险是OAuth2.0本身是授权框架而非认证协议，需要在OpenID Connect层做额外封装。此风险在2020年Q2的技术预研中已验证可行。"

你看，同样是写文档，多花15分钟把决策四元组填上，三年后的价值天差地别。

3. 为什么大多数团队做不到？不是懒，是对文档的定位错了

我观察到的现象是，大多数团队不是不愿意写好文档，而是他们从骨子里把文档当成"交付物"而不是"资产"。

交付物的特征是：交出去就完事了，质量高低不影响我自己。资产的特征是：我以后还要用，所以我要维护它、更新它、让它持续产生价值。

当一个团队把文档定位为"应付甲方验收的东西"，他们自然会追求页数多、看起来很专业，但不会费心去记录决策背景。因为甲方验收时不会问"你们为什么这么设计"，他们只看功能有没有实现。

但当一个团队把文档定位为"团队共同的记忆外挂"，情况就完全不同了。他们会在每次评审会上主动更新决策记录，会要求新人先读决策文档再读代码，会在系统出现问题时第一时间回溯决策文档寻找线索。

这种定位差异，是区分"文档堆砌"和"决策记录"的根本原因。

三、瀑布模型为什么尤其需要决策记录？这得从它的基因说起

要理解这个问题，我们需要回到瀑布模型的核心假设上。很多人批判瀑布模型，说它假设需求是稳定的、不变更的。这个批判对了一半。瀑布模型的真正假设不是"需求不会变"，而是"变更的成本会随着时间指数级上升，所以必须在前期尽可能把关键决策做对、做透、记录下来"。

这个假设在很多行业里是成立的。比如一个银行核心系统的利率计算模块，如果上线后发现计算逻辑有问题，修复成本可能是百万级别的资金损失加监管处罚。这种情况下，前期花两周时间把利率计算规则讨论清楚、记录在案、多方评审，就是绝对划算的投资。

1. 瀑布的"阶段门"机制，本质上是决策关卡

我画过一张图来描述瀑布模型的本质。表面上它是一条流水线：需求→设计→开发→测试→部署。但如果你从"决策密度"的角度重新看，它其实是五个密集决策的关卡：

• 需求阶段：决定"做什么"和"不做什么"，以及优先级排序
• 设计阶段：决定"怎么做"，包括架构、技术栈、模块划分
• 开发阶段：决定每个模块的具体实现方式
• 测试阶段：决定验收标准和缺陷容忍度
• 部署阶段：决定上线策略和回滚方案

每个关卡产出的文档，本质上应该是该阶段的"决策包"，而不是简单的"工作记录"。需求规格说明书不是"用户说了什么"的会议纪要，而是"我们经过分析、权衡后，决定实现什么"的决策声明。设计文档不是"系统有哪些模块"的目录，而是"为什么这样划模块、为什么选这个架构"的决策推演。

2. 为什么敏捷团队的文档可以少，但瀑布团队不行？

这里我需要澄清一个常见的误解。很多人说："你看Facebook、Google这些公司，敏捷开发，文档很少，不也做得很好？为什么我们就非得写那么多文档？"

这个类比忽略了一个关键差异：敏捷团队的"文档"是分散在代码注释、Slack聊天记录、Jira工单、PR描述和团队成员的大脑里的。他们的团队稳定、人员流动可控、系统架构相对清晰，隐性知识可以通过每日站会和结对编程有效传递。

但瀑布模型的主流应用场景，银行、政府、军工、大型制造业，往往面临完全不同的约束：

• 团队规模大，经常跨部门、跨公司协作
• 人员流动不可避免，三年前的开发者大概率已经不在
• 系统生命周期长，可能运行10年以上
• 合规和审计要求高，需要能追溯每一个关键决策
• 甲方和乙方之间存在信息不对称，文档是合同的一部分

在这些约束下，如果你不把决策记录下来，等于把项目的长期可维护性押在了"核心人员的稳定性"上。而在我见过的项目里，这个赌注通常都会输。

3. 一个真实教训：核心架构师离职后，300万行代码成了"文物"

2021年我接手了一个制造企业ERP系统的升级项目。系统是2015年用Java开发的，300万行代码，设计文档有，但不全，最关键的是没有决策记录。

原始团队的核心架构师在2018年离职了，之后的三年里，接手的团队遇到任何需要改动核心模块的需求，都采取一个策略：在外面包一层，尽量不动原来的代码。

到2021年，这个系统已经包了四层"外壳"，性能和可维护性都到了崩溃边缘。我们尝试梳理原系统的设计逻辑，但只能从代码反推，效率极低。有些业务规则明显是当时基于特定约束做的妥协，但现在没人知道那个约束是否还存在，所以不敢改。

最后这个项目花了预算的2.8倍才完成升级，主要成本都花在了"考古"上。如果当年的架构师在离职前花一周时间，把关键决策的背景和理由写下来，这个成本至少可以降低60%。

这个教训让我坚信：在长周期的瀑布项目里，决策记录不是锦上添花，而是生存必需。

四、从"要你写"到"你想写"：如何建立决策记录的纪律

前面讲了为什么要写决策记录，接下来讲怎么落地。这部分来自我在几个团队里推行的实践经验，有成功也有失败，我把能复用的方法论提炼出来。

1. 决策记录的颗粒度：不是所有事都值得记

很多人一听到"决策记录"，第一反应是"这得加多少工作量"。这个担心是合理的。如果要求团队事无巨细地记录每一个决定，那文档很快就会变成另一种形式的堆砌。

我的实践法则是：只记录那些"如果不记录，未来会导致重大误解或重复讨论"的决策。具体来说，满足以下任一条件的决策必须记录：

• 影响范围大：涉及多个模块或系统的交互方式
• 违反直觉：你选择了一个看起来不是最优但有其特殊原因的方案
• 不可逆或极难逆转：数据库选型、核心协议选择、对外接口定义
• 有争议：团队内部对这个决策有过激烈讨论
• 基于临时约束：当时因为时间、预算、技术限制做的妥协，未来约束可能解除

举个反例：你选择用HashMap还是TreeMap来实现一个内部缓存，这个通常不需要写决策记录，因为影响范围小且容易修改。但你选择用Redis还是本地内存来做缓存架构，这就是一个应该记录的决策。

2. 决策记录的模板：简单到不会成为负担

我给团队设计的决策记录模板只有五个字段，可以嵌入在任何现有文档中：

这个模板的优势在于：它是增量信息，不是重复劳动。传统的文档里你本来就要写"系统采用XX方案"，现在只是多写几行，把这个方案背后的思考过程也写出来。额外增加的工作量通常不超过每个决策10-15分钟。

3. 什么时机写最有效？在决策发生的当下，而不是事后

我踩过的一个坑是：要求团队在迭代结束后统一补文档。结果是，要么不补，要么补出来的质量很差，因为当时的讨论细节已经忘了。

后来我改了一个策略：把决策记录嵌入到现有的评审流程中，让它在决策发生的当下就完成。具体做法是：

• 需求评审会：评审通过的每个用户故事，必须在故事卡片上附带"优先级决策理由"，一句话说明为什么这个故事的优先级是P0而不是P1
• 技术方案评审：方案文档的模板里直接包含"备选方案分析"和"已知风险"两个章节，不写完整就不算评审通过
• 线上问题复盘：每次P0/P1故障的复盘报告，必须包含"当时的决策链路回顾"，找到是哪个决策出了问题

这个做法的底层逻辑是：不要增加新的流程节点，而是在现有流程节点上增加产出标准。团队不需要额外的动力去写文档，因为不写的话评审过不了。这个约束比任何"文档规范培训"都有效。

4. 让决策记录"活"起来：它不该被写在文档里就死掉

决策记录最大的敌人不是写不写，而是写了没人看。当一个团队积累了上百条决策记录，但没有人去查阅和更新，那这些记录就会变成另一种形式的"文档堆砌"。

我在一个金融科技团队推行的做法是：

• 新人入职：前两周的主要任务之一是通读核心模块的决策记录，然后在第三周做一个"决策回溯"分享，讲清楚他认为哪些决策今天看来仍然成立，哪些可能需要重新审视
• 需求变更评审：任何涉及核心模块的需求变更，必须先查阅该模块的历史决策记录，确认变更是否会与既有决策冲突
• 季度决策审计：每季度由架构师牵头，对过去一个季度的关键决策做一次回溯，标记哪些决策已经被后续决策覆盖或推翻，更新决策状态

这些做法的共同思路是：决策记录不是写完就归档的"死文档"，而是持续参与团队思考的"活资产"。它的价值不仅在于被查阅，更在于被质疑、被更新、被推翻，当一条决策被正式推翻时，新决策会引用旧决策的编号并说明推翻理由，这就形成了一条完整的决策演化链。

五、以PingCode为例看工具如何支撑决策记录

前面讲了理念和方法，这里我想结合一个具体的工具案例来展示"决策记录"在实践中如何落地。我选择PingCode作为例子，是因为我实际参与过它的实施咨询，而且它在中大型企业的瀑布与敏捷混合场景中应用较多。

先说明一下背景：PingCode主要服务的是100人以上的中大型组织，这类组织的特点恰恰是前面分析的，项目周期长、团队规模大、人员流动不可避免、合规审计要求高。这些特征天然要求团队在管理需求、规划迭代、跟踪进度时，把"决策"作为一个核心资产来对待。

1. 需求管理中的"决策锚点"

在传统文档模式下，需求就是一条一条的"系统应支持XX功能"。但在PingCode的Scrum解决方案中，需求是以"史诗-特性-用户故事"三级结构管理的，每一级都提供了设定优先级和业务价值的入口。

这个设计看似简单，实际上是把"决策"嵌入了需求管理的日常操作中。产品负责人在对需求排序时，不是凭感觉拖拽，而是要在系统中明确标识优先级和业务价值分值。这个动作本身就是一种决策记录，它告诉团队：在当前迭代，我们认为这个需求比那个需求更重要，依据是业务价值更高。

我在一个客户项目上做过一个实验：两个月内不要求团队额外写任何文档，只要求他们在PingCode中严格执行"优先级+业务价值"的填写。两个月后回溯，我们发现仅凭这些结构化数据，就能还原出当时的产品决策逻辑，准确率达到80%以上。

这个实验让我意识到：好的工具设计可以让决策记录"无感发生"。团队不需要专门花时间写决策文档，他们在正常使用工具的过程中，已经自然地把关键判断留了下来。

2. 迭代规划中的"集体决策现场"

在PingCode的Scrum流程中，迭代规划会是一个关键的决策节点。产品负责人讲解需求，团队一起确定迭代待办列表，然后把用户故事拆分成具体的开发任务。

从决策记录的角度看，这个过程产生了两层决策信息：

• 第一层：哪些需求进入本次迭代，哪些被推迟。这个选择本身就是基于优先级、资源、依赖关系的综合判断。在PingCode里，迭代待办列表就是一份"本次迭代的决策声明"。
• 第二层：用户故事被拆分成哪些任务。这个拆分方式反映了团队对实现路径的判断。为什么这个功能要分成3个任务而不是2个？为什么这个任务由后端先做而不是前端？这些都是技术决策的体现。

传统文档模式下，这些决策大多发生在白板上或者口头上，散会后就不见踪影。但在PingCode里，迭代待办列表和任务拆分的结果是持久化的、可追溯的。三个月后你想复盘"为什么这个迭代延期了"，你可以精确地看到当时的任务量估算和实际完成情况的对比，而不需要去翻会议纪要或者回忆。

3. 进度跟踪中的数据驱动决策回溯

PingCode的迭代概览页面提供了燃尽图和用户故事点燃尽情况。这些看似只是进度管理工具，实际上它们是决策效果的"反馈器"。

举个例子：一个迭代进行到一半时，燃尽图显示实际进度远慢于理想线。这时候团队需要做一个决策：是加班赶工，还是调整迭代范围，还是接受延期？这个决策以及它的依据，是基于燃尽图的趋势判断，还是基于某个突发风险，如果在当时被记录下来，对未来的项目规划就是极其宝贵的参考。

我在一个团队里推行的做法是：每次发现燃尽图出现异常偏离时，由Scrum Master在迭代备注中写一条简短的"异常决策记录"，内容包括：发现时间、偏离程度、原因分析、采取的应对措施。积累了几次迭代后，这些记录就成了一本"风险管理案例集"，新上任的Scrum Master可以直接参考。

4. 评审与回顾：决策记录的"纠错闭环"

PingCode支持在迭代完成后进行评审和回顾，迭代回顾板可以记录"做得好"、"做得不好"和"改进计划"。这个设计实际上是在帮团队建立一个决策的"纠错闭环"。

我观察到的一个常见问题是：很多团队在回顾会上讨论得热火朝天，但记录下来的只有寥寥几条，而且通常比较虚，比如"加强沟通"、"提高代码质量"。这些记录过了一个月基本就被遗忘了。

我的改进建议是：把回顾的产出聚焦到"决策修正"上。具体而言，每个"做得不好"的项，必须对应到某个之前做出的决策，是哪个决策导致了这个问题？我们需要修正的是这个决策本身，还是决策的执行方式？然后，在下一个迭代的规划中明确这个修正动作，并在迭代结束时回溯修正效果。

这个做法让回顾会从一个"情绪抒发"的场合变成了一个"决策质量持续改进"的管理回路。回顾记录不再是放在Wiki里积灰的页面，而是直接嵌入到下一轮迭代的决策输入中。

5. 多产品数据互通带来的决策全景图

PingCode的一个设计特点是Project模块可以与Testhub、Wiki、Insight等其他产品数据互通。这个互通的价值在于，它让分散在不同环节的决策记录可以被串联成一条完整的决策链路。

举个实际场景：一个需求从Wiki中产生（记录了业务背景和初步方案讨论），在Project中被拆分为用户故事和开发任务（记录了迭代优先级和任务分解决策），在Testhub中关联了测试计划和缺陷（记录了质量判断和缺陷修复决策），在Insight中通过效能数据展示了交付效果（记录了资源投入决策的实际产出）。

这条链路构成了一个完整的"决策全景图"。当项目复盘时，你可以从任何一个节点切入，顺着关联关系还原当时的决策逻辑。这是传统文档模式无法做到的，传统模式下，需求文档、设计文档、测试报告各自独立，要还原一条完整的决策链需要大量的人工追溯。

当然，我并不是说用了PingCode就能自动拥有高质量的决策记录。工具只是降低了记录和追溯的成本，真正决定质量的是团队是否养成了"记录决策背景"的习惯。但一个好的工具确实可以通过流程设计和数据关联，让这个习惯更容易养成。

六、不同场景下的决策记录策略：不是所有项目都需要同一套标准

前面讲了决策记录的理念、方法和工具支撑，这一节我要给出一个更务实的讨论：在不同的项目场景下，你需要多重的决策记录？一刀切地要求所有项目都做完整的决策四元组记录，既不现实也不必要。

我根据项目的"系统生命周期"和"变更风险"两个维度，把决策记录分为三个等级。

1. 轻量级决策记录：适用于生命周期短、风险低的项目

如果你在做的是一个内部工具、一个营销活动页面、或者一个生命周期预期不超过一年的临时系统，那么完整的决策四元组记录可能确实是过度投入。

但"轻量级"不等于"不记录"。我建议这类项目至少做到：

• 在代码仓库的README中用一到两段话写清楚项目的核心设计思路。不是写"技术栈是Spring Boot + MySQL"这种能从代码里看出来的东西，而是写"为什么这个项目存在"、"核心业务流程是什么"、"有哪些反直觉的设计需要注意"。
• 在关键接口和复杂逻辑处写注释时，不只写"这行代码做什么"，更要写"为什么这么做"。比如"这里用了一个看似多余的缓存，因为第三方接口有每日调用限额，实测发现不加缓存会在高峰期触发限流"。

这些记录的投入产出比极高，通常一个项目只需要额外投入一两个小时，但可以把后续维护时的"考古成本"降低50%以上。

2. 标准级决策记录：适用于中长周期、有一定合规要求的项目

这是我在第二节详细阐述的"决策四元组"标准。适用于：

• 系统预期生命周期在3年以上
• 涉及外部客户或合作伙伴
• 有基本的合规或审计要求
• 团队规模在10人以上，或预期会有人员交接

在这种场景下，决策记录应该成为设计评审和需求评审的产出物之一，而不是额外的工作。每个关键决策点都需要包含：背景、备选方案、选择理由、已知风险、决策人与日期。

一个实践中有效的判断标准是：在项目的任何时间点，如果核心团队全部更换，新团队能否通过阅读决策记录文档，在一周内理解系统的关键设计逻辑和约束条件？如果能，说明决策记录的质量达标；如果不能，说明还有关键信息遗漏。

3. 严苛级决策记录：适用于超长周期、高监管、高风险的领域

这一级主要适用于：金融核心系统、政府关键基础设施、军工系统、医疗设备软件、航空航天控制软件等。

在这些领域，决策记录不仅是工程资产，更是法律证据和合规材料。决策记录需要能够支撑外部审计师或监管机构在多年后回溯任何一个关键判断。

严苛级的要求在标准级基础上增加了：

• 决策追溯链：每个决策都要有唯一编号，后续决策如果修改或推翻前序决策，必须引用编号并说明原因
• 决策评审签名：关键决策需要多方评审并在文档中留存签名或电子签章
• 决策与测试的映射：需求决策要能关联到具体的测试用例，设计决策要能关联到代码审查记录
• 定期回溯机制：每季度或每半年对存量决策做一次有效性审查，标记已过时的决策

我参与过一个城商行核心系统的项目，他们达到了这个级别。审计的时候，银监会的检查官随机抽了五个核心业务规则，要求项目组在半小时内提供这几个规则的决策依据、评审记录和测试覆盖情况。他们做到了，因为系统里每一个业务规则都有完整的决策追溯链。这个能力不是突击加班能做到的，是日积月累的纪律。

七、当决策记录遇到现实阻力：常见反对意见及应对

在推决策记录实践的过程中，我遇到过各种反对声音。有些是合理的担忧，有些是误解。这一节我把最常见的几种反对意见拿出来逐个分析。

1. "我们敏捷了，不需要文档"，混淆了敏捷的"轻文档"和"零决策记录"

这是我最常听到的反对意见。很多团队在从瀑布转向敏捷后，把"减少文档"理解为"不需要记录"，从一个极端走向另一个极端。

敏捷的"可工作的软件高于详尽的文档"，说的是执行的优先级，不是说决策可以不记录。一个采用了Scrum的团队，在迭代评审会上展示可工作的软件，但如果在迭代回顾会上不记录"我们决定在下个迭代改进什么"，那这个团队的持续改进能力就会严重受限。

我的回应通常是：敏捷的文档策略应该是"决策记录"而不是"文档废除"。把精力花在记录那些真正影响系统演进的决策上，砍掉那些纯粹为了应付流程的文档。这不是加法，是替换。

2. "写了也没人看"，这是流程问题，不是记录本身的问题

这个反对意见背后通常有一个真实的问题：团队的文档确实写了一大堆，但从来没有人查阅。这个问题的根源不是"决策记录没用"，而是"文档没有被纳入工作流程"。

如果决策记录只是安静地躺在Wiki的某个角落，没人提醒、没人引用、没人更新，那它确实会变成废纸。解决方法是把决策记录"嵌入流程"，需求变更时强制回溯相关决策记录，事故复盘时强制引用历史决策，新人入职时强制阅读核心决策。

我在第六节已经详细讲了这些嵌入机制，这里不再重复。核心观点是：不要让"写了没人看"成为你不写的理由，而是去建立"看了才有用"的正反馈循环。

3. "决策太快来不及记录"，其实15分钟就够了

这个反对意见通常来自高强度运转的技术团队。他们觉得在紧张的开发节奏中，根本没有时间停下来写东西。

我的回应分两部分。

第一，决策记录不需要长篇大论。我在第四节给出的"决策四元组"模板，填写一个决策通常只需要10-15分钟。如果你连15分钟都没有，那这个决策可能真的不那么重要，可以不记录。但如果你即将做出一个影响系统未来三年演进的关键架构选择，你确定15分钟都挤不出来吗？

第二，决策记录的时间应该计入决策本身的成本。一个没有被记录的决策，本质上是一个"半成品决策"。你以为你做了决策，但实际上你只做了选择，没有留下任何追溯依据。这个决策的长期价值大打折扣。把15分钟计入决策时间，是让这个决策从"半成品"变成"成品"的必要工序。

4. "系统会重构，文档会过时"，这才是决策记录最有价值的时刻

这个反对意见的逻辑是：既然代码会变、架构会演进，那基于当时情况的决策记录很快就没有参考价值了。

我恰恰认为，正因为系统会演进，决策记录才更有价值。当你准备重构一个模块时，最危险的不是没有文档，而是你不知道这个模块当初为什么被设计成这样，哪些约束在当时是成立的，哪些约束今天可能已经不存在了。

一份高质量的决策记录能帮你回答这个问题。它会告诉你：当初选A方案是因为约束X，现在约束X已经解除了（比如原来限制性能的硬件升级了），所以我们可以考虑换成B方案。如果没有这个记录，你可能要花大量时间做"考古"，然后因为不了解当时的约束而不敢改动。

至于"文档过时"的问题，关键在于：决策记录不需要维护成"当前最新状态"，它只需要准确地反映"当时的决策状态"。当决策被后续决策覆盖时，不需要修改原决策记录，只需要在新决策记录中引用并说明覆盖原因。这样，决策记录就变成了一条完整的演化链路，而不是一份需要不断修改的快照。

八、结论：把决策记录变成团队的肌肉记忆

写到这里，我想把整篇文章的核心观点再凝练一次。

瀑布开发之所以被诟病，不是因为它的阶段划分和文档要求本身有错，而是因为大量的瀑布实践把"写文档"当成了目的，而不是手段。文档成了应对验收的交付物、掩盖沟通不足的遮羞布、填充工时的橡皮图章。但这不是文档的问题，是写文档的方式和意识的问题。

决策记录的价值可以从三个层面来理解：

• 对个人：它是你"想清楚"的外部证据。逼自己在写方案时把备选方案和选择理由写出来，其实是在逼自己想得更透彻。
• 对团队：它是集体记忆的外置硬盘。核心成员离职不再是灾难，因为关键判断都留在了决策记录里。
• 对组织：它是工程能力的复利资产。每一个项目的决策记录，都是下一个项目可以借鉴的经验库，让组织不再重复踩坑。

对于正在阅读这篇文章的你，不管你是项目经理、架构师、还是普通的开发者，我给你的下一步行动建议只有一句话：

从下次设计评审会开始，在你的方案文档里加两个小节，"备选方案分析"和"已知风险与缓解"。不用改变整个团队的文档体系，不用推动组织级的流程变革，就从你自己的方案开始。写两次之后，你会发现写这两个小节的过程，本身就是对你思考质量的一次内检。如果你写不出来这两个小节，说明你对方案的思考可能还没有到位。

这个动作很小，但它是一个起点。当团队里开始有人先做到"为自己的决策留下证据"，这种习惯就会慢慢扩散。最终，它不再是"公司要求写文档"，而是"我想把我想清楚的记录下来"。这个转变一旦发生，决策记录就不再是负担，而是专业性的自然延伸。

瀑布不会死，但只会堆砌文档的瀑布一定会死。活下来的，是那些把每一份文档都当成决策声明来写的团队。