32 lines
1.5 KiB
Markdown
32 lines
1.5 KiB
Markdown
|
# 寫作 ADR (Write ADR) 技能指南
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
`write_adr` 是可交付技能，用來產生架構決策記錄（ADR），包含 Context、Decision、Consequences 與 Alternatives。供 `design-architecture` 在產生 ADR 章節時參考。
|
|||
|
|
|
|||
|
|
## 核心原則
|
|||
|
|
ADR 為每個重要架構決策提供永久記錄。包含決策背後的理由、考慮的替代方案與權衡取捨。
|
|||
|
|
|
|||
|
|
## 何時寫 ADR
|
|||
|
|
為以下任何決策寫 ADR：
|
|||
|
|
- 影響系統結構或服務邊界
|
|||
|
|
- 涉及技術選擇（語言、框架、資料庫、佇列、快取、基礎設施）
|
|||
|
|
- 涉及一致性模型選擇
|
|||
|
|
- 涉及安全架構決策
|
|||
|
|
- 涉及重大取捨（效能 vs 一致性、複雜度 vs 簡單性）
|
|||
|
|
- 難以或昂貴逆轉的決策
|
|||
|
|
- 其他工程師會質疑「為什麼這樣選？」的決策
|
|||
|
|
|
|||
|
|
## ADR 格式
|
|||
|
|
每個 ADR 必須包含：
|
|||
|
|
- **Context**：為什麼需要這個決策，什麼問題或情境需要決定，什麼 PRD 需求驅動了這個決策
|
|||
|
|
- **Decision**：決定了什麼，清楚且具體地陳述，包含選擇的特定技術、模式或方法
|
|||
|
|
- **Consequences**：這個決策帶來的取捨，正面與負面都要
|
|||
|
|
- **Alternatives**：考慮過什麼其他選項，每個選項的描述與不被選中的理由
|
|||
|
|
|
|||
|
|
## 防範佔位符規則
|
|||
|
|
範例僅供說明用途。不要重複使用範例中的佔位符 ADR 標題、Context、Decision 或 Alternatives。
|
|||
|
|
|
|||
|
|
## 不應做的事
|
|||
|
|
- 不替非實際架構決策寫 ADR
|
|||
|
|
- 不複製範例的內容當作自己的決策
|
|||
|
|
- 不產生獨立 ADR 檔案（所有 ADR 必須嵌入 `docs/architecture/{feature}.md`）
|