# 寫作 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`）