ADR 撰寫器
以清晰背景、替代方案與影響記錄架構決策。請使用英文撰寫。
ADR 範本
# ADR-[編號]: [簡短決策標題]
**狀態:** [提案 | 已接受 | 已棄用 | 被 ADR-XXX 取代]
**日期:** [YYYY-MM-DD]
**作者:** [名稱/代號]
## 1. 背景
我們正在解決什麼問題？有哪些因素影響它（商業目標、技術負債、預算）？
**限制條件：**
- [限制條件 1]
- [限制條件 2]
## 2. 決策
決策的簡短陳述。主要論點。
## 3. 技術細節與機制
_自由格式章節。描述實作細節、資料結構、協定細節或關鍵框架功能。_
- [列表、API 描述、資料結構]
- [Mermaid 圖表（建議用於複雜互動）]
## 4. 考慮的替代方案
### 4.1. [選項 1]
- **優點：** ...
- **缺點：** ...
- **決策：** [已拒絕/已考量]（簡短原因）。
## 5. 影響與風險
### 正面影響（優點）
- 這對系統/團隊有何幫助？
### 負面影響 / 風險（缺點/風險）
- 我們接受哪些缺點？威脅是什麼？
- **緩解措施：** 我們將如何處理這些風險？
## 6. 修訂歷史
- **[日期]**: [變更說明] ([作者])
- **[日期]**: [例如：狀態變更為「已接受」] ([作者])
ADR 編號規則
ADR-001: 初始系統架構
ADR-002: 分析用資料庫選擇
ADR-003: 認證策略
...
狀態工作流程
提案 → 已接受 → 已實施
↓
已拒絕
已接受 → 已棄用 → 被 ADR-XXX 取代
最佳實踐
- 為重大決策撰寫 ADR：並非每個選擇都需要 ADR
- 記錄替代方案：展示你考慮過其他選項
- 坦誠面對權衡取捨：每個決策都有缺點
- 保持簡潔：最多 1-2 頁
- 更新狀態：標記已棄用/被取代的 ADR
- 連結相關 ADR：建立決策軌跡
- 包含後續事項：附有負責人的行動項目
- 視覺化：使用 Mermaid 圖表展示架構與流程
- 為未來的讀者撰寫：他們缺乏當前背景
- 誠實面對權衡取捨（每個選擇都有缺點）
常見模式
技術選型：
- 專注於技術能力是否符合需求
- 如果有的話，包含性能基準測試
- 記錄團隊專業程度
- 考慮營運複雜度
架構變更：
- 在影響部分包含遷移策略
- 記錄向後相容性影響
- 考慮過渡期間的團隊開發速度影響
- 記錄監控與回滾計畫
標準與慣例：
- 包含標準的實際範例
- 記錄例外或脫離機制
- 考慮執行機制
- 注意教育訓練/新人入職影響
棄用：
- 將狀態設為「已棄用」或「被取代」
- 連結到取代它的 ADR
- 記錄日落時間表
- 包含遷移指南
反模式
❌ 過於詳細：沒人會讀的 10 頁 ADR ❌ 沒有替代方案：看起來像是預先決定的 ❌ 缺少影響：忽略缺點 ❌ 沒有負責人：無人負責 ❌ 過時的狀態：舊的 ADR 仍標為「提案」
審查核對清單
- 背景中有清楚的問題陳述
- 決策已明確陳述
- 考慮了 2 個以上替代方案
- 誠實評估了權衡取捨
- 記錄了影響（正面與負面）
- 已識別風險並有緩解措施
- 已指派決策負責人
- 有截止日期的後續行動
- 狀態為最新
輸出核對清單
- 已建立 ADR 文件
- 背景說明了問題
- 決策已清楚陳述
- 記錄了 2-3 個替代方案
- 權衡取捨章節已填寫
- 列出了影響（正面與負面）
- 已識別風險並有緩解措施
- 決策日期與負責人
- 已指派後續行動
- 狀態已設定