1.5 KiB

Raw Blame History

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