Adr Assistant

---
name: adr
source: ../../../../skills/adr-assistant/SKILL.md
source_version: 1.0.0
source_hash: a5c79c6a04fe
translation_version: 1.1.0
last_synced: 2026-08-17
status: current
description: |
  [UDS] 建立、管理並追蹤架構決策記錄（ADR）。
  Use when: 架構決策、技術選型、設計取捨、模式選擇。
  Not for: 不改變架構的決策——記在規格或 commit 裡即可；想法還沒成形到足以下決定——請用 /brainstorm。
  Keywords: ADR, architecture decision, decision record, trade-off, 架構決策, 決策記錄, 設計取捨.
allowed-tools: Read, Write, Glob, Grep
scope: universal
argument-hint: "[create | list | supersede ADR-NNN | 決策主題]"
---

# 架構決策記錄助手

> **語言**: [English](../../../../skills/adr-assistant/SKILL.md) | 繁體中文

建立、管理和追蹤架構決策記錄。捕捉重大技術決策的背景、選項和理由。

## 工作流程

```
CAPTURE ──► ANALYZE ──► DECIDE ──► RECORD ──► LINK
  捕捉背景    分析選項    做出決策    記錄 ADR    建立連結
```

### 階段 1：CAPTURE | 捕捉背景

識別驅動決策的背景與限制條件。

| 步驟 | 動作 |
|------|------|
| 1 | 識別問題或機會 |
| 2 | 列出限制條件（時間、預算、團隊技能） |
| 3 | 定義決策驅動因素 |

### 階段 2：ANALYZE | 分析選項

至少探索 2 個選項，列出優缺點。

| 步驟 | 動作 |
|------|------|
| 1 | 腦力激盪候選方案 |
| 2 | 根據決策驅動因素評估各方案 |
| 3 | 記錄各方案優缺點 |

### 階段 3：DECIDE | 做出決策

選擇最佳方案並闡述理由。

### 階段 4：RECORD | 記錄 ADR

依照標準模板產生 ADR 檔案。

### 階段 5：LINK | 建立連結

與相關工件（規格、PR、程式碼）建立交叉引用。

## 快速參考

### 何時撰寫 ADR

| 撰寫 ADR | 不需要 ADR |
|----------|-----------|
| 框架/函式庫選擇 | 例行性依賴更新 |
| API 合約或資料格式 | 現有架構內的 Bug 修復 |
| 部署策略變更 | 程式碼風格決策 |
| 建立新模式 | 瑣碎的實作選擇 |

**經驗法則**：如果 6 個月後有人可能會問「為什麼？」，就寫一份 ADR。

### 狀態生命週期

```
Proposed ──► Accepted ──► Deprecated
                │
                └──► Superseded by ADR-NNN
```

| 狀態 | 說明 |
|------|------|
| **Proposed** | 討論中，尚未決定 |
| **Accepted** | 已接受，應遵循 |
| **Deprecated** | 不再適用 |
| **Superseded** | 已被新 ADR 取代 |

### 模板摘要

```markdown
# ADR-NNN: [決策標題]

- Status: [Proposed | Accepted | Deprecated | Superseded]
- Date: YYYY-MM-DD
- Deciders: [參與決策者]
- Technical Story: [SPEC-ID 或 Issue]

## Context（背景）
## Decision Drivers（決策驅動因素）
## Considered Options（考慮的選項）
## Decision Outcome（決策結果）
### Consequences（後果：Good / Bad / Neutral）
## Links（相關連結）
```

### 存放位置

```
docs/adr/
├── ADR-001-short-description.md
├── ADR-002-short-description.md
└── README.md    # 索引（可選）
```

## 指令

| 指令 | 說明 |
|------|------|
| `/adr` | 互動式建立 ADR |
| `/adr create` | 建立新 ADR |
| `/adr list` | 列出所有 ADR 及狀態 |
| `/adr search [關鍵字]` | 依關鍵字搜尋 ADR |
| `/adr supersede [ADR-NNN]` | 取代現有 ADR |
| `/adr review` | 審查過期的 ADR |

## 與其他技能的整合

| 技能 | 整合方式 |
|------|---------|
| `/sdd` | 在技術設計中引用 ADR；重大決策時建議建立 ADR |
| `/code-review` | 程式碼審查時引用 ADR 作為設計依據 |
| `/commit` | 提交時在 footer 加入 ADR 編號 |
| `/brainstorm` | 腦力激盪結果作為 ADR 選項分析輸入 |

## 品質檢查清單

| 檢查項目 | 標準 |
|----------|------|
| ☐ 背景 | 清楚說明問題 |
| ☐ 選項 | 至少考慮 2 個選項 |
| ☐ 驅動因素 | 決策驅動因素明確列出 |
| ☐ 後果 | 包含正面與負面結果 |
| ☐ 連結 | 相關工件已引用 |

## 下一步引導

`/adr` 完成後，AI 助手應建議：

> **ADR 已建立。建議下一步：**
> - 執行 `/sdd` 建立規格（若決策需要實作）
> - 執行 `/commit` 提交 ADR 檔案
> - 更新相關規格以引用此 ADR
> - 若狀態為 `Proposed`，分享給團隊審查

## AI 代理行為

當使用者呼叫 `/adr` 時，AI 助手必須：

1. **檢查現有 ADR** — 搜尋 `docs/adr/` 以確定下一個 ADR 編號
2. **互動式引導** — 逐步詢問背景、驅動因素和選項
3. **產生檔案** — 將 ADR 寫入 `docs/adr/ADR-NNN-title.md`
4. **建議連結** — 識別相關規格或 ADR 以建立交叉引用
5. **提供下一步** — 顯示上方的下一步引導

當使用者呼叫 `/adr list` 時：
1. 掃描 `docs/adr/` 目錄
2. 解析每個 ADR 檔案的狀態
3. 以表格顯示：編號、標題、狀態、日期

當使用者呼叫 `/adr supersede [ADR-NNN]` 時：
1. 讀取現有 ADR
2. 引導建立新 ADR
3. 將舊 ADR 狀態更新為 `Superseded by ADR-NNN`
4. 在新 ADR 中加入 `Supersedes ADR-NNN`

## 參考

- 核心規範：[adr-standards.md](../../../../core/adr-standards.md)
- 詳細指南：[guide.md](./guide.md)