[TOC] ## 什么是“設計決策記錄”（Architectural Decision Records，ADRs） 設計決策記錄 (ADRs) 是一種記錄軟件開發過程中關鍵設計決策及其背后原因的文檔方法。它幫助團隊捕捉在開發中做出的重要架構或設計選擇，解釋為什么選擇了某種方案，以及在當時的情況下有哪些權衡。ADRs 通常以輕量級的文本文件形式存在，適合長期維護的項目和團隊知識共享。 ## 為什么需要 ADRs？ 1. **清晰記錄決策歷史**： * 讓團隊成員理解過去的設計選擇，特別是對新成員很重要。 * 避免重復討論或錯誤。 2. **知識共享與上下文傳遞**： * 幫助團隊在變更時了解為什么做出某個設計。 * 提供變更上下文，便于未來做調整。 3. **決策可追溯性**： * 隨時間推移，團隊可以回溯特定設計的原因和影響。 * 有助于審查時提供透明性。 4. **團隊對齊**： * 通過記錄和討論 ADR，團隊可以達成共識。 ## 什么是“設計決策記錄”（Architectural Decision Records，ADRs）？ **設計決策記錄 (ADRs)** 是一種記錄軟件開發過程中關鍵設計決策及其背后原因的文檔方法。它幫助團隊捕捉在開發中做出的重要架構或設計選擇，解釋為什么選擇了某種方案，以及在當時的情況下有哪些權衡。ADRs 通常以輕量級的文本文件形式存在，適合長期維護的項目和團隊知識共享。 ## 為什么需要 ADRs？ 1. **清晰記錄決策歷史**： * 讓團隊成員理解過去的設計選擇，特別是對新成員很重要。 * 避免重復討論或錯誤。 2. **知識共享與上下文傳遞**： * 幫助團隊在變更時了解為什么做出某個設計。 * 提供變更上下文，便于未來做調整。 3. **決策可追溯性**： * 隨時間推移，團隊可以回溯特定設計的原因和影響。 * 有助于審查時提供透明性。 4. **團隊對齊**： * 通過記錄和討論 ADR，團隊可以達成共識。 ## ADR 的存儲與管理 ### 版本控制： ADR 文件通常保存在代碼倉庫的 docs/adr 文件夾中，作為團隊共享文檔。 工具支持： 可以使用開源工具（如 adr-tools）自動生成 ADR 模板并進行管理。 命名規則： 文件名通常包含決策的序號和簡短標題，例如：001-use-reactjs.md。 ## ADR 的典型結構 ADRs 通常基于 Michael Nygard 提出的模板結構，內容如下： 1. **標題**：決策的名稱（簡潔且描述性）。 2. **上下文**：問題背景及為什么需要做這個決策。 3. **決策**：做出的具體決定是什么。 4. **理由**：為什么選擇這個解決方案（包括考慮的權衡點）。 5. **替代方案**：列出其他考慮過的方案以及為什么未被采納。 6. **后果**：當前決策可能帶來的影響，包括技術債務或未來需要變更的部分。 ## 適用場景 * **技術選型**：選擇框架、語言、庫、工具。 * **架構變更**：微服務拆分、數據庫設計、API 策略。 * **性能優化**：權衡不同性能方案。 * **團隊流程**：如是否采用代碼審查流程、CI/CD 工具等。 ## 示例 ### 標題：選擇 React.js 作為前端框架 上下文： 項目需要一個動態前端框架。 團隊成員對現有技術棧（如 Vue.js 和 Angular）存在分歧。 項目要求有高性能和組件化能力，并且需要與現有的后端 API 無縫集成。 決策： 決定采用 React.js 作為項目的前端框架。 理由： React.js 是一個成熟且活躍的框架，擁有強大的社區支持。 團隊中已有 60% 成員熟悉 React，可以快速上手。 React 的組件化設計適合項目需求，并且其虛擬 DOM 提供了高性能的 UI 渲染。 替代方案： Vue.js：容易學習，但團隊中熟悉的人較少。 Angular：功能強大，但復雜度較高，學習成本較大。 后果： 短期內能提高開發效率，因為大部分開發者已經熟悉 React。 長期來看，需要密切關注 React 的版本升級和與后端的兼容性問題。