AsiaOstrich 架構決策記錄助手
語言: English | 繁體中文
建立、管理和追蹤架構決策記錄。捕捉重大技術決策的背景、選項和理由。
工作流程
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 取代 |
模板摘要
# 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 助手必須：
- 檢查現有 ADR — 搜尋
docs/adr/以確定下一個 ADR 編號 - 互動式引導 — 逐步詢問背景、驅動因素和選項
- 產生檔案 — 將 ADR 寫入
docs/adr/ADR-NNN-title.md - 建議連結 — 識別相關規格或 ADR 以建立交叉引用
- 提供下一步 — 顯示上方的下一步引導
當使用者呼叫 /adr list 時：
- 掃描
docs/adr/目錄 - 解析每個 ADR 檔案的狀態
- 以表格顯示：編號、標題、狀態、日期
當使用者呼叫 /adr supersede [ADR-NNN] 時：
- 讀取現有 ADR
- 引導建立新 ADR
- 將舊 ADR 狀態更新為
Superseded by ADR-NNN - 在新 ADR 中加入
Supersedes ADR-NNN
參考
- 核心規範：adr-standards.md
- 詳細指南：guide.md