Skip to main content

ADR 模板

本頁定義架構決策紀錄（ADR）的標準格式，供團隊記錄重大架構選型與決策。

模板​

# ADR-NNN: 決策標題

> ADR = Architecture Decision Record

## 狀態

**Proposed | Accepted | Deprecated** - YYYY-MM-DD

## 背景

描述觸發此決策的問題或需求：
- 目前遇到什麼問題？
- 為什麼需要做出決策？
- 有哪些限制條件？

## 討論

分析各方案的優缺點：

| 方案 | 優點 | 缺點 |
|------|------|------|
| 方案 A | ... | ... |
| 方案 B | ... | ... |

技術考量、效能影響、維護成本等。

## 決策

明確說明最終選擇的方案及理由。

可包含架構圖、程式碼範例、設定選項。

## 影響

- **正面影響**：帶來的好處
- **負面影響**：可能的風險或限制
- **Breaking Changes**：需要配合修改的地方

## 實作計畫

分階段執行步驟，如有 Linear Issue 可在此引用。

## 相關文件

- 連結到相關的 spec、設計文件、外部參考

## 版本歷程

| 日期 | 版本 | 變更說明 |
|------|------|----------|
| YYYY-MM-DD | 1.0 | 初始提案 |

使用指南​

何時需要寫 ADR​

  • 引入新的第三方框架或函式庫
  • 變更核心架構模式（例如通訊機制、儲存策略）
  • 跨模組的介面設計決策
  • 影響多個專案的共用元件變更

編號規則​

  • 格式：ADR-NNN，三位數字流水號
  • 從 ADR-001 開始遞增
  • 已 Deprecated 的編號不重複使用

狀態流轉​

Proposed → Accepted → (Deprecated)
  • Proposed：已提出但尚未通過 review
  • Accepted：經團隊討論確認採用
  • Deprecated：已被新決策取代，需註明替代的 ADR 編號

Mermaid 圖表建議​

ADR 的核心價值在於記錄「為什麼選 A 不選 B」。純文字描述選項差異往往不如一張圖清楚，建議在撰寫時主動加入 Mermaid 區塊。圖表類型速查見 Mermaid 圖表使用指南；範本在 internal/standards/mermaid-templates/。

在「## 討論」加入：選項對比 flowchart​

為每個方案畫一張結構圖，並列比較：

方案 A 架構（範例）

方案 B 架構（範例）

在「## 決策」加入：最終架構 flowchart​

明確展示最終採用的結構：

決策邏輯複雜時：決策樹 flowchart​

讓讀者能自我判斷該採用哪個分支的配置：

撰寫提醒​

  • 所有節點名稱要具體（用業務術語而非 A、B）
  • 轉換 / 決策分支要標 label（是 / 否 / 觸發事件）
  • MDX 跳脫注意：inline code 內 {、} 需寫成 &#123;、&#125;；prose 裡 <|-- 這類圖形符號寫成 &lt;|--
  • 圖前後要有一段文字說明，避免「孤圖」