您的程式碼庫有文檔記錄，但您的決策沒有。

大多數運作良好的工程團隊都擁有合理的程式碼文件：註解、README、API 文件、類型簽章和 docstring。程式碼本身就是系統功能的一種文件形式。一個有能力的工程師在閱讀程式碼庫時，可以理解任何組件的當前行為。

但他們僅憑程式碼無法理解的是：為什麼。

為什麼驗證服務是一個獨立的微服務，而不是單體架構中的一個模組？為什麼數據管道使用批次處理而不是串流處理？當有更受歡迎的替代方案時，為什麼要使用這個特定的函式庫來進行 HTTP 請求？為什麼 Schema 中有一個名為 legacy_status 的欄位，它被填入了資料卻從未被讀取？

這些問題中的每一個都有答案，且該答案在過去的某個時間點被討論、辯論並決定。討論可能發生在 Slack 討論串、會議或 PR 註解中。決定做出了，程式碼寫好了，而背後的推論卻蒸發了。

遺失決策的代價

當決策背後的推論遺失時，會發生兩件事。

新工程師會犯團隊已經犯過的錯誤。 一個不知道為什麼驗證服務與單體架構分離的工程師可能會提議將它們合併，花了一週時間建立概念驗證，然後在審查中得知這種分離的存在是因為兩年前歷經千辛萬苦才發現的延遲問題。這一週的時間被浪費了，因為推論沒有被記錄下來。

已解決的決策會被重新爭論。 有人提出了數據管道應該採用批次還是串流的問題。團隊花了一次會議的時間來辯論。辯論到一半，有人想起這在一年前就討論過，當時的結論是串流需要更改基礎架構，而這不值得為了解決延遲問題而做出改動。這次會議被浪費了，因為先前的決策及其推論無法被找到。

這兩種成本在當下都是隱形的（它們看起來就像正常的工程討論），但在累計起來卻非常巨大（同一個決策被辯論多次，同一個錯誤被接任的工程師重複，每當有新成員接觸系統時，同一個脈絡就必須從頭重建）。

決策文件的樣貌

決策文件不需要很複雜。其核心要素為：

問題。 當時在決定什麼？以一個清晰、可搜尋的問題來呈現。

考慮過的選項。 當時討論了哪些替代方案？即使是簡短的清單也很有價值，因為它表明當前的做法是經過選擇的，而不是預設的。

決策。 最終選擇了什麼？

推論。 為什麼選擇這個選項？接受了哪些權衡？如果要重新審視這個決策，需要改變什麼？

日期與參與者。 這是何時決定的，有哪些人參與？

這種格式有時被稱為架構決策記錄 (Architecture Decision Record, ADR)，持續使用它的團隊一致報告說，這顯著減少了決策重複爭論和新員工加入時的阻力。

自動化的角度

決策文件面臨的挑戰與所有文件一樣：它需要有人去寫，而做出決策的時刻，鮮少有人會想寫一份關於它的文件。

自動撰寫的文件可以從實際做出決策的源頭擷取決策。一個團隊辯論兩種方法並得出結論的 Slack 討論串，可以自動總結為一份決策記錄。一場討論架構選項的會議，可以從會議記錄中產生一份結構化的文件。一個解釋了非顯而易見設計選擇的 PR 描述，可以連結到更廣泛的決策歷史中。

決策已經在做出。討論已經在進行。缺少的是擷取，而從現有管道進行自動擷取，遠比要求工程師在事後寫下他們的決策要可靠得多。

常見問題

對於小決策來說，這是不是大材小用？ 並非每個決策都需要正式文件。其界限在於：如果你預期新工程師在遇到它時會問「為什麼要這樣做？」，那麼其推論就應該被記錄下來。關於基本架構、技術選擇和重大權衡的決策，幾乎總是符合這個標準。

決策文件應該存放在哪裡？ 與系統文件放在一起，可搜尋並連結到相關的程式碼或系統。一個與工程維基分離的決策日誌總比沒有好，但不如與其相關的系統文件相整合的決策來得實用。

我們如何溯及既往地記錄過去的決策？ 從造成最多阻力的決策開始：那些最常被重新爭論，或新工程師最常問到的決策。向還記得的成員寫下其背後的推論，並接受較舊的決策可能需要被標記為「重建」而非絕對權威。

延伸閱讀：巴士係數、隱性知識的隱形成本、文件債。相關頁面：自動撰寫文件、決策日誌、給工程團隊。