线上故障复盘会开到一半，有人问起某个接口当初为什么这样设计。在场的人给出三种说法，有人说当时评估过另一个方案，有人说那个方案早就被否了，至于否决的理由，没有人记得。只能去翻半年前的聊天记录，翻了很久，只找到一句结论。
这个场景在很多研发团队里反复出现。讨论的时候人都在，信息也齐全，讨论结束之后，决策就散在消息流、会议上的口头结论和几个人的记忆里。过一段时间再问，谁都不敢确定当初是怎么定的。
这篇不推荐工具，只讨论一个具体问题：研发团队的技术决策怎么留存。要回答它，得先看清丢的是哪一层，再按讨论、评审、需求变更三类场景分别处理。
一、研发团队的技术决策为什么留不住
1、三个反复出现的现场
有一种现场是同一个问题被重复讨论。半年前定过一次，项目负责人换了，又重新讨论一遍，结论还可能和上次不一样。
另一种现场是需求改过之后，团队对改动范围的认知不一致。产品记得改过，开发记得只是加了个字段，测试的用例还是按旧口径写的，问题要到联调阶段才暴露。
还有一种现场是老成员离开或者转岗，某个模块的判断依据跟着消失。接手的人只能从代码里反推，反推不出当初的取舍。
2、讨论没少，丢的是结论
讨论不稀缺，稀缺的是讨论结束时那句可以被引用的话。
一段讨论的结束标志，常常是没人再说话了，而不是形成了一句写清楚的结论。消息流还在，检索也能搜到，但完整的上下文要重新读一遍才能拼出来。
真正需要留存的是三样东西：当时的背景、评估过的选项、最终的选择和理由。聊天记录保存的是过程，不是决策。
3、哪些决策值得留存
不是所有讨论都要记录。值得留下来的，通常是影响跨模块或跨团队的、回滚代价高的、几个月后还需要向人解释的决策。
反过来，写法约定、命名习惯、一次性的排查过程，放在原来的位置就够了。留存范围放得太大，记录这件事本身就会先失败。先划清这个范围，再谈记录方式，动作才不容易变形。
二、判断问题卡在哪一层
上面三种现场看着相似，卡住的位置却不一样。改流程之前，先花十分钟判断问题出在哪一层。
1、载体这一层
打开团队的沟通工具，搜一个半年前的关键决策。如果能搜到明确的结论，这一层没有问题。如果搜到的是一串需要重新阅读的对话，说明决策没有独立的位置。
2、形式这一层
回顾上一次评审会，问一句：会议结束的时候，有没有产生一份能当作结论的东西。只有讨论记录而没有结论，下一个接手的人仍然要重新判断一遍。
3、关联这一层
需求变更之后，受影响的开发和测试能不能被及时通知到。如果结论和需求、任务、版本之间没有关联，变更就只能靠人挨个打招呼，漏掉谁全凭运气。
4、一张对照表定位问题层级
| 观察到的现象 | 判断信号 | 优先修复的方向 |
|---|---|---|
| 结论只能靠翻聊天记录找到 | 决策没有独立载体 | 给结论固定落点 |
| 讨论过，但没人说得清结论 | 缺少收口动作 | 讨论结束当场收口 |
| 变更后有人不知道，联调才暴露 | 结论与需求任务没有关联 | 建立关联与通知 |
三层的修复顺序不建议颠倒。越过判断直接采购工具，多数时候只是把分散的记录换个地方继续分散。任何一层留着没解决，记录都会慢慢失效。
三、讨论的留存：给结论一个独立的位置
讨论是决策产生的起点，也是结论最容易丢掉的地方。
1、讨论可以散，结论必须收
约定一个收口动作。讨论结束时由主持人或者提议人写一句结论，附上理由和仍然待定的部分。谁负责收口要事先指定，不能默认落到发起人身上。
收口不要求写成长文，三五行写清楚就够，但这件事要当天做完，隔一天回忆就会失真。
2、给每类讨论一个固定的落点
日常方案讨论、评审会、变更沟通，分别应该落在什么位置，团队需要事先约定。
约定好之后有一个直接好处：找结论时不用猜它在哪个软件里。临时交流照旧在群组里进行，需要被保留的结论统一放在同一个位置。
3、搜不到等于没留
留存能不能生效，取决于检索。按关键词、按参与者、按时间范围，至少要有一种路径能快速定位到当时的结论。
多端同步同样关键。如果结论只存在某一位同事的电脑上，它就不算留下来了。结论沉淀在机构自建的服务端，账号和数据由机构自己掌握，成员通过终端接入访问，留存和权限控制才能同时成立。
四、评审的留存：结论和理由都要留下
讨论解决了结论能不能被找到，评审还要解决另一件事，结论能不能被读懂。
1、只记结论，三个月后就没人懂
架构决策记录里有一条被广泛采用的做法：记录只追加，不修改。决策发生变化时，新增一条记录，并标明它取代了哪一条。
这么做保留了方向变化的时间和原因。后来的人看到的不是一份被反复改写的文档，而是一串可以追溯的判断。
2、一条合格的评审记录要写清什么
| 字段 | 写清楚的样子 | 等于没写的样子 |
|---|---|---|
| 背景与问题 | 具体到场景和约束 | 一句技术升级需要 |
| 备选方案 | 至少写出被放弃的那个 | 只写最终方案 |
| 取舍理由 | 说明为什么不选另一个 | 只写选了哪个 |
| 影响范围 | 涉及模块、接口、排期 | 不写影响 |
| 复审条件 | 什么情况下需要重新评估 | 不写 |
表格的第三列是最常见的写法，写的人当场看得懂，三个月后的人看不懂。评审记录的价值不在篇幅，而在这五个字段有没有落到实处。
3、被否掉的方案更要留
没被采纳的方案和否决理由，是很少被写下来的部分，也是后来被反复重新提出的部分。
当时把握不大的决策也值得记录。写清楚这一点，将来重新评估时就有依据，不必推倒重来。
五、需求变更的留存：让每次改动都能追溯
评审管的是做决定的那一刻，需求变更管的是决定之后的变化。
1、没有基线，就说不清改了什么
判断一项内容属于新增还是原有，前提是有一份当前有效的范围说明，包含要交付的内容、验收标准，以及这一版明确不做的部分。
版本不统一的时候，先统一版本，再讨论变化。否则双方各按自己的版本执行，争的其实不是方案。
2、变更要留住影响分析
一条变更记录需要回答五件事：改什么、为什么改、影响哪些模块和测试范围、增加多少工作量与风险、谁做的决定。
比如一个字段改名，看起来只动了一处文案，实际可能牵涉数据库、接口和导入模板。只记录改了什么而不记录代价，同类变更还会再来一次。
3、口头承诺不算记录
讨论里的零散意见可以作为线索，但不能自动成为执行依据。团队需要明确，只有进入记录并经过确认的结论才生效。
六、研发团队怎么验证留存机制有没有生效
机制立起来之后，研发团队还需要有办法判断它是不是真的在起作用。观察三个信号就够了。
1、看新人上手要不要重新问一遍
新成员能不能通过检索独立还原某个模块的决策背景，是判断机制是否有效的一个直接信号。如果每个新人都要挨个问老同事，记录就还停在形式上。
2、看同类问题会不会被反复决策
统计一段时间内重复出现的议题。如果同一类问题在几个月里被讨论了三次，说明前两次的结论没有被用起来。
3、机制跑偏的三种常见样子
一是只写结论不写理由，记录变成了通知。二是记录散在太多位置，检索成本反而上升。三是把记录动作压在某一个人身上，这个人一忙，记录就停。
对应的矫正动作也简单：把理由写成必填，把位置收敛到一处，把收口动作分摊到每次讨论的主持人。
机制不必一次铺开。先在一个小组、一类决策上试行，跑顺了再扩大范围。
总结
回到开头那场复盘会。让人为难的从来不是选择本身，而是选择的依据已经找不到。
技术决策的留存，考验的不是工具采购能力，而是一支研发团队把口头共识转成可追溯记录的习惯。它由三个动作组成：讨论结束当场收口，评审记录写清理由，变更留下影响分析。
这三个动作不会让研发团队少讨论一次，但会让下一次讨论从结论开始，而不是从回忆开始。
