architecture-decision-records

架構決策記錄

在編寫程式碼的過程中即時記錄架構決策。與其讓決策只存在於 Slack 討論串、PR 評論或某人的記憶中，這個技能會產出結構化的 ADR 文件，與程式碼共存。

何時啟用

• 使用者明確說「我們記錄這個決定」或「ADR 這個」
• 使用者在重要的替代方案之間做選擇（框架、函式庫、模式、資料庫、API 設計）
• 使用者說「我們決定...」或「我們做 X 而不是 Y 的原因是...」
• 使用者問「為什麼我們選 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

當偵測到決策時機時：

1. 初始化（僅第一次） — 如果 docs/adr/ 不存在，請在使用者確認後才建立目錄、一個包含索引表標頭的 README.md（見下方 ADR 索引格式），以及一個供手動使用的空白 template.md。未經明確同意不得建立檔案。
2. 識別決策 — 提取正在做出的核心架構選擇
3. 收集背景 — 是什麼問題引發這個決策？有哪些限制？
4. 記錄替代方案 — 考慮過哪些其他選項？為什麼被拒絕？
5. 陳述影響 — 有哪些取捨？哪些事情變得更簡單或更困難？
6. 分配編號 — 掃描 docs/adr/ 中的現有 ADR 並遞增
7. 確認並寫入 — 將 ADR 草稿呈現給使用者審查。僅在獲得明確批准後才寫入 docs/adr/NNNN-decision-title.md。如果使用者拒絕，則丟棄草稿，不寫入任何檔案。
8. 更新索引 — 附加到 docs/adr/README.md

閱讀現有 ADR

當使用者問「為什麼我們選 X？」時：

1. 檢查 docs/adr/ 是否存在 — 如果不存在，回覆：「此專案中未找到 ADR。是否要開始記錄架構決策？」
2. 如果存在，掃描 docs/adr/README.md 索引以尋找相關條目
3. 讀取相符的 ADR 檔案，並呈現背景與決策章節
4. 如果找不到相符項目，回覆：「未找到該決策的 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