再聊對架構決策記錄的一些思考

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 有著非常高的潛在價值，極度推薦大家在團隊中進行實踐。保持文件結構的簡潔輕量和討論的開放性，團隊會非常樂於接受和參與這種高效的決策程和知識同步過。