1 引言

第一次在社区发文聊 ADR（架构决策记录）是在 2022 年 8 月份，在文章（ 轻量级ADR机制 ）中，详细介绍了以下几个主题：

•团队研发面临的主要问题

•ADR 的结构剖析

•ADR 的存储形式

•ADR 在研发流程中所处的位置

•ADR 常见的误区与疑问

在实践中发现仍然有一些普遍性问题与挑战可以探讨。

2 研发团队一些普遍现象

视角一：架构决策缺失是问题长期存在的普遍问题，但团队普遍缺少治理

普遍存在的现象是团队对系统演进过程中的关键架构决策缺乏记录，虽然需求迭代过程中技术团队会产生系列的“技术方案”，依靠这些“技术方案”追溯系统的关键决策和演进依然面临挑战：

•其一，“技术方案”一般会随着不同需求迭代散落在文档系统中，不便于整合

•其二，技术方案是设计决策的“快照”信息，其体现的是决策的结果，并不能反映决策的演进过程和还原决策的上下文

•其三，技术方案一般是长文档，其“过期和不一致”的概率较大，多数情况下团队缺少对历史技术方案的维护修正。

组织架构及业务调整，团队面临接手新的系统，或者新的团队成员的加入，面对遗留/新的系统，快速熟悉系统是高效支持迭代建设的前提。但，大多数情况对遗留系统的了解过程困难重重，很多时候依赖于可能已经过期和散落的技术方案（技术视角），或者不得不梳理系统代码以获得更多系统知识。

对于技术而言，如果能有清晰明确的决策记录一定程度上能够加速了解系统的效率，降低认知成本。不论是从对现有系统知识的沉淀梳理，还是团队间技术决策的同步，亦或是在系统交接场景下提升信息传递效率，ADR 都是极具性价比且极易落地的实践。

视角二：对 ADR 的排斥

很多同学“排斥”ADR 的原因常见的是：

•其一：文档化与技术人员的第一直觉相悖：“不太愿意花太多的精力在文档撰写上”

•其二：排斥“评审”：认为 ADR 的评审是一种强流程的正式评审，大家不愿意参加“评审会”，发起人也“不愿意抛出自己的决策让大家在会上讨论”。这显然与 ADR 机制相悖，本质上，团队实践的应当是一种非常轻量级的、不应有太多负担的架构决策机制，大家头脑风暴式的讨论、共识。

•其三：不确定什么场景下需要写 ADR，会觉得实践过程无准则可依

对于原因一和原因二的解决方式非常简单：保持 ADR 模版的简单和轻量，打破对文档化的固有认知

对于原因三，其实多数情况下系统负责人可以明确的感知哪些决策对团队或系统的影响“比较大”，比如：

•新建子系统或系统职责合并

•引入新的技术组件/框架或者中间件等基础设施

•工程结构的重大调整

•代码规范的变更

•其他

视角三：技术氛围不够开放，团队自组织程度较低

ADR 是一种架构决策，与参与系统建设的每个人息息相关，其关键价值不仅仅在于决策的留存和追溯，更为重要是在于通过干系人的讨论使得决策知识在团队间高效同步。大家对决策的制定共同参与、共识，越开放的氛围越有利于对决策充分探讨，同时也有利于决策有效落地。

同时，敏捷文化推行的轻文档机制与轻量级 ADR 并不冲突，ADR 与敏捷文化相契合，在“自组织”团队中天然的适合引入 ADR。

3 建议

建议一：先做起来，写一个 ADR 邀请团队成员一起讨论、决策共识

建议二：ADR 保持足够轻量，在体现其价值的同时尽量减少团队负担

建议三：构建开放的技术氛围【重要】

讨论氛围一定要保持开放，切忌一言堂、强压式的决策，让团队成员都参与进来，抛出自己的观点或疑问，直到决策共识、通过

4 结语

不论是从管理视角还是技术视角，ADR 有着非常高的潜在价值，极度推荐大家在团队中进行实践。保持文档结构的简洁轻量和讨论的开放性，团队会非常乐于接受和参与这种高效的决策程和知识同步过。