AsiaOstrich ADR Assistant | 架構決策記錄助手
Language: English | 繁體中文
Create, manage, and track Architecture Decision Records. Capture the context, options, and rationale behind significant technical decisions.
建立、管理和追蹤架構決策記錄。捕捉重大技術決策的背景、選項和理由。
Workflow | 工作流程
CAPTURE ──► ANALYZE ──► DECIDE ──► RECORD ──► LINK
捕捉背景 分析選項 做出決策 記錄 ADR 建立連結
Phase 1: CAPTURE | 捕捉背景
Identify the context and constraints driving the decision.
識別驅動決策的背景與限制條件。
| Step | Action | 步驟 |
|---|---|---|
| 1 | Identify the problem or opportunity | 識別問題或機會 |
| 2 | List constraints (time, budget, team skills) | 列出限制條件 |
| 3 | Define decision drivers | 定義決策驅動因素 |
Phase 2: ANALYZE | 分析選項
Explore at least 2 options with pros and cons.
至少探索 2 個選項，列出優缺點。
| Step | Action | 步驟 |
|---|---|---|
| 1 | Brainstorm candidate options | 腦力激盪候選方案 |
| 2 | Evaluate each against decision drivers | 根據決策驅動因素評估 |
| 3 | Document pros/cons for each | 記錄各方案優缺點 |
Phase 3: DECIDE | 做出決策
Select the best option and articulate the rationale.
選擇最佳方案並闡述理由。
Phase 4: RECORD | 記錄 ADR
Generate the ADR file following the standard template.
依照標準模板產生 ADR 檔案。
Phase 5: LINK | 建立連結
Cross-reference with related artifacts (SPECs, PRs, code).
與相關工件（規格、PR、程式碼）建立交叉引用。
Quick Reference | 快速參考
When to Write an ADR | 何時撰寫 ADR
| Write ADR | Skip ADR |
|---|---|
| Framework/library choice | Routine dependency update |
| API contract or data format | Bug fix within existing architecture |
| Deployment strategy change | Code style decision |
| Establishing new patterns | Trivial implementation choice |
Rule of thumb: If someone might ask "why?" in 6 months, write an ADR.
經驗法則：如果 6 個月後有人可能會問「為什麼？」，就寫一份 ADR。
Status Lifecycle | 狀態生命週期
Proposed ──► Accepted ──► Deprecated
│
└──► Superseded by ADR-NNN
| Status | Description | 說明 |
|---|---|---|
| Proposed | Under discussion | 討論中 |
| Accepted | Active, should be followed | 已接受，應遵循 |
| Deprecated | No longer relevant | 不再適用 |
| Superseded | Replaced by newer ADR | 已被新 ADR 取代 |
ADR Template Summary | 模板摘要
# ADR-NNN: [Title]
- Status: [Proposed | Accepted | Deprecated | Superseded]
- Date: YYYY-MM-DD
- Deciders: [people]
- Technical Story: [SPEC-ID or Issue]
## Context
## Decision Drivers
## Considered Options
## Decision Outcome
### Consequences (Good / Bad / Neutral)
## Links
Storage | 存放位置
docs/adr/
├── ADR-001-short-description.md
├── ADR-002-short-description.md
└── README.md # Index (optional)
Commands | 指令
| Command | Action | 說明 |
|---|---|---|
/adr |
Interactive ADR creation wizard | 互動式建立 ADR |
/adr create |
Create a new ADR | 建立新 ADR |
/adr list |
List all ADRs with status | 列出所有 ADR 及狀態 |
/adr search [keyword] |
Search ADRs by keyword | 依關鍵字搜尋 ADR |
/adr supersede [ADR-NNN] |
Supersede an existing ADR | 取代現有 ADR |
/adr review |
Review ADRs for staleness | 審查過期的 ADR |
Integration with Other Skills | 與其他技能的整合
| Skill | Integration | 整合方式 |
|---|---|---|
/sdd |
Reference ADRs in Technical Design; suggest creating ADR for major decisions | 在技術設計中引用 ADR |
/code-review |
Reference ADRs as design rationale during code review | 程式碼審查時引用 ADR |
/commit |
Include ADR-NNN in commit footer for traceability |
提交時在 footer 加入 ADR 編號 |
/brainstorm |
Feed brainstorm output into ADR option analysis | 腦力激盪結果作為 ADR 選項分析輸入 |
Quality Checklist | 品質檢查清單
Before accepting an ADR:
| Check | Criteria | 標準 |
|---|---|---|
| ☐ Context | Clearly explains the problem | 清楚說明問題 |
| ☐ Options | At least 2 options considered | 至少考慮 2 個選項 |
| ☐ Drivers | Decision drivers explicitly listed | 決策驅動因素明確列出 |
| ☐ Consequences | Both good and bad outcomes | 包含正面與負面結果 |
| ☐ Links | Related artifacts referenced | 相關工件已引用 |
Next Steps Guidance | 下一步引導
After /adr completes, the AI assistant should suggest:
ADR created. Suggested next steps:
- Execute
/sddto create a spec if the decision requires implementation- Execute
/committo commit the ADR file- Update related SPECs to reference this ADR
- Share with team for review if status is
Proposed
ADR 已建立。建議下一步：
- 執行
/sdd建立規格（若決策需要實作）- 執行
/commit提交 ADR 檔案- 更新相關規格以引用此 ADR
- 若狀態為
Proposed，分享給團隊審查
AI Agent Behavior | AI 代理行為
When the user invokes /adr, the AI assistant MUST:
- Check existing ADRs — Search
docs/adr/to determine next ADR number - Guide interactively — Ask about context, drivers, and options step by step
- Generate the file — Write ADR to
docs/adr/ADR-NNN-title.md - Suggest links — Identify related SPECs or ADRs to cross-reference
- Offer next steps — Show the Next Steps Guidance above
When the user invokes /adr list:
- Scan
docs/adr/directory - Parse status from each ADR file
- Display as a table: Number, Title, Status, Date
When the user invokes /adr supersede [ADR-NNN]:
- Read the existing ADR
- Guide creation of a new ADR
- Update old ADR status to
Superseded by ADR-NNN - Add
Supersedes ADR-NNNto new ADR
Reference | 參考
- Core Standard: adr-standards.md
- Detailed Guide: guide.md