adr

# 架構決策記錄助手 > **語言**: [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)