架構決策記錄 (ADR)
在編碼工作階段中捕捉架構決策。這些決策不再只存在於 Slack 討論串、PR 評論或某人的記憶中，而是產生結構化的 ADR 文件，與程式碼共存於專案中。
啟用時機
- 使用者明確說「讓我們記錄這個決定」或「ADR 這個」
- 使用者在重要的替代方案之間做選擇（框架、函式庫、模式、資料庫、API 設計）
- 使用者說「我們決定要...」或「我們這麼做而不是那麼做的原因是...」
- 使用者問「我們為什麼選擇 X？」（讀取現有 ADR）
- 在規劃階段討論架構權衡取捨時
ADR 格式
採用 Michael Nygard 提出的輕量級 ADR 格式，並針對 AI 輔助開發進行調整：
# ADR-NNNN：[決策標題]
**日期**：YYYY-MM-DD
**狀態**：proposed | accepted | deprecated | superseded by ADR-NNNN
**決策者**：[參與者]
## 背景脈絡
我們看到什麼樣的問題，促使了這個決策或變更？
[2-5 句話描述情境、限制條件與影響因素]
## 決策
我們提議及/或正在進行的變更是什麼？
[1-3 句話清楚陳述決策]
## 考慮過的替代方案
### 替代方案 1：[名稱]
- **優點**：[好處]
- **缺點**：[壞處]
- **不採納原因**：[拒絕此方案的具體理由]
### 替代方案 2：[名稱]
- **優點**：[好處]
- **缺點**：[壞處]
- **不採納原因**：[拒絕此方案的具體理由]
## 影響
因為這個變更，哪些事情變得更容易或更困難？
### 正面影響
- [好處 1]
- [好處 2]
### 負面影響
- [取捨 1]
- [取捨 2]
### 風險
- [風險與緩解措施]
工作流程
捕捉新的 ADR
當偵測到決策時刻時：
- 初始化（僅限首次） — 如果
docs/adr/目錄不存在，請在使用者確認後再建立目錄、一個內含索引表格表頭（見下方 ADR 索引格式）的README.md，以及一個供手動使用的空白template.md。未經明確同意，不得建立任何檔案。 - 識別決策 — 提取核心的架構選擇
- 收集脈絡 — 什麼問題引發了這個決策？存在哪些限制條件？
- 記錄替代方案 — 考慮過哪些其他選項？為何被拒絕？
- 陳述影響 — 有哪些權衡取捨？哪些事情變得更容易/更困難？
- 指定編號 — 掃描
docs/adr/中的現有 ADR 並遞增編號 - 確認並寫入 — 向使用者呈現 ADR 草稿供審查。僅在使用者明確批准後，才寫入
docs/adr/NNNN-decision-title.md。如果使用者拒絕，則捨棄草稿，不寫入任何檔案。 - 更新索引 — 將新條目附加到
docs/adr/README.md
讀取現有 ADR
當使用者問「我們為什麼選擇 X？」時：
- 檢查
docs/adr/是否存在 — 如果不存在，回覆：「此專案中找不到任何 ADR。您想要開始記錄架構決策嗎？」 - 如果存在，掃描
docs/adr/README.md索引以尋找相關條目 - 讀取相符的 ADR 檔案，並呈現「背景脈絡」與「決策」章節
- 如果找不到相符項目，回覆：「找不到該決策的 ADR。您想要現在記錄一個嗎？」
ADR 目錄結構
docs/
└── adr/
├── README.md ← 所有 ADR 的索引
├── 0001-use-nextjs.md
├── 0002-postgres-over-mongo.md
├── 0003-rest-over-graphql.md
└── template.md ← 供手動使用的空白模板
ADR 索引格式
# 架構決策記錄
| ADR | 標題 | 狀態 | 日期 |
|-----|------|------|------|
| [0001](0001-use-nextjs.md) | 使用 Next.js 作為前端框架 | accepted | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | 選擇 PostgreSQL 而非 MongoDB 作為主要資料儲存 | accepted | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | 選擇 REST API 而非 GraphQL | accepted | 2026-02-01 |
決策偵測訊號
在對話中留意以下模式，這些模式表示一項架構決策：
明確訊號
- 「我們用 X 吧」
- 「我們應該用 X 而不是 Y」
- 「這個取捨是值得的，因為...」
- 「把這個記錄為 ADR」
隱含訊號（建議記錄 ADR — 未經使用者確認不得自動建立）
- 比較兩個框架或函式庫後得出結論
- 基於明確理由做出資料庫綱要設計選擇
- 在架構模式之間做選擇（單體 vs 微服務、REST vs GraphQL）
- 決定驗證/授權策略
- 評估替代方案後選擇部署基礎設施
良好 ADR 的要素
應該做
- 要具體 — 使用「使用 Prisma ORM」而非「使用一個 ORM」
- 記錄原因 — 理由比結果更重要
- 包含被拒絕的替代方案 — 未來的開發者需要知道考慮過哪些選項
- 誠實陳述影響 — 每個決策都有取捨
- 保持簡短 — 一份 ADR 應可在 2 分鐘內閱讀完畢
- 使用現在式 — 使用「我們使用 X」而非「我們將使用 X」
不該做
- 記錄瑣碎的決定 — 變數命名或格式化選擇不需要 ADR
- 寫成長篇大論 — 如果「背景脈絡」章節超過 10 行，就太長了
- 遺漏替代方案 — 「我們就是選了它」不是有效的理由
- 未標記狀態就補記錄 — 如果記錄的是過去的決策，請註明原始日期
- 讓 ADR 過時 — 被取代的決策應引用其替代者
ADR 生命週期
proposed → accepted → [deprecated | superseded by ADR-NNNN]
- proposed：決策正在討論中，尚未定案
- accepted：決策生效並正在被遵循
- deprecated：決策已不再相關（例如功能已移除）
- superseded：較新的 ADR 取代了這個（務必連結取代者）
值得記錄的決策類別
| 類別 | 範例 |
|---|---|
| 技術選擇 | 框架、語言、資料庫、雲端服務商 |
| 架構模式 | 單體 vs 微服務、事件驅動、CQRS |
| API 設計 | REST vs GraphQL、版本策略、驗證機制 |
| 資料建模 | 綱要設計、正規化決策、快取策略 |
| 基礎設施 | 部署模型、CI/CD 管道、監控堆疊 |
| 安全性 | 驗證策略、加密方法、機密管理 |
| 測試 | 測試框架、涵蓋率目標、端到端 vs 整合測試的平衡 |
| 流程 | 分支策略、審查流程、發布節奏 |
與其他技能的整合
- 規劃代理人：當規劃者提出架構變更時，建議建立一個 ADR
- 程式碼審查代理人：標記那些引入了架構變更卻沒有對應 ADR 的 PR