先決定你現在是要學，還是要在專案裡做
網站負責解釋與分發工作包；真正的 Repository 掃描、缺口判斷與文件產出交給 Coding Agent。
SDLC 實作課 · 交付物練習
先理解這份文件替你消除什麼不確定
把「為什麼這樣選」寫下來，半年後不用考古
半年後新人問「為什麼用 Kafka 不用 RabbitMQ？」沒人記得；老人離職後決策的脈絡全失。
ADR 把每個重要架構決策寫成短文件：context / options / decision / consequences。
沒有 ADR，後人要嘛盲目沿用、要嘛盲目重做，兩種都有成本。
誰負責、交給誰
主責： Architect（最終決策與簽核）
協作： Dev Lead（驗證可實作）、SRE（驗證可營運）、SA（補規格脈絡）
下游收件： 全工程團隊（決策可追溯）、新人 onboarding
何時值得做
必要時機： 跨服務影響、不可逆決策（DB、framework、protocol）、有 ≥ 2 合理選項
不需要時： 局部模組設計、可逆的小決策、純風格選擇
常見誤用： 把 ADR 當作技術說明書（要寫 trade-off，不寫 how-to）；Status 字段不維護（Superseded 不標）
- 01讀大綱
- 02看案例
- 03填素材
- 04貼提示詞
- 05對照驗收
Anatomy · 文件解剖
輕量版先回答 6 個核心章節
章節名稱可以因團隊調整，但每一段要求的判斷不能被省略。先讀問題，再看格式。
- 01
Context
範本必要章節
3-5 行說明當前問題、約束、為何現在需要決策
- 02
Decision Drivers
範本必要章節
至少列 3 個 driver，每個帶權重原因。輕量版可省略 5 象限要求
- 03
Options Considered
範本必要章節
≥ 2 個選項（含「保持現狀」或「不做」），每個都要 pros/cons 至少各 1
- 06
Decision & Consequences
範本必要章節
把已確認的內容、判斷依據與仍待補充的資訊清楚分開。
- 10
Decision Log
範本必要章節
每條必含 chosen + 至少 1 個 rejected option + 拒絕原因
- 12
Confidence & Sources & TODO
範本必要章節
把已確認的內容、判斷依據與仍待補充的資訊清楚分開。
Study · 對照學習
同一份交付物，先練核心，再看完整深度
輕量範本適合第一次練習與 MVP；完整範本保留跨職能交棒需要的細節。兩者都要求未知事項保持可見。
30 分鐘內先完成核心章節。
---
doc_type: "adr"
variant: "light"
status: "proposed"
owner: "<your-name>"
last_updated: "YYYY-MM-DD"
upstream:
required: ["technical-discussion-notes"]
optional: ["prd", "c4-diagram", "nfr"]
---
# ADR-NNN: <短描述決策題目>
**Status:** Proposed · **Owner:** <Architect name> · **Last updated:** YYYY-MM-DD
> [!IMPORTANT]
> **AI 填寫規則：** 本範本 6 段（編號 1, 2, 3, 6, 10, 12），全部必填——刻意沿用完整版的章節編號讓兩版可對照。每結論行內加 `（依據：discussion §XXX）`；每量化欄位加 `[H]/[M]/[L]` confidence badge；缺資料寫 `_TODO: 需要 XXX_` 不編造選項；ADR 是**單一決策原子文件**，若 input 含多個決策必須拆多份輸出。
---
## 1. Context
<!-- ai-fill: 3-5 行說明當前問題、約束、為何現在需要決策 -->
<3-5 行說明當前面對的問題與約束>
> **TL;DR:** <一句話：為何需要這個決策>
---
## 2. Decision Drivers
<!-- ai-rule: 至少列 3 個 driver，每個帶權重原因。輕量版可省略 5 象限要求 -->
| Driver | Weight | Why this matters |
|---|---|---|
| <e.g. Time-to-market> | High | <為何此優先> |
| <e.g. Operability> | Medium | ... |
---
## 3. Options Considered
<!-- ai-rule: ≥ 2 個選項（含「保持現狀」或「不做」），每個都要 pros/cons 至少各 1 -->
### Option A: <name>
- **Pros:** <好處 1>、<好處 2>
- **Cons:** <代價 1>、<代價 2>
- **Cost:** <一次性 + 經常性>
### Option B: <name>
...
---
## 6. Decision & Consequences
### Chosen: **Option A** · **[H]**
- **Scope:** <適用範圍 / 不適用範圍>
- **Positive consequences:** <好處>
- **Negative consequences（必填）:** <代價，例：選 Kafka 需新增 KRaft 維運負擔>
- **Follow-up:** <後續需處理事項>
---
## 10. Decision Log
<!-- ai-rule: 每條必含 chosen + 至少 1 個 rejected option + 拒絕原因 -->
| Date | Decision | Options | Chosen | Rejected why | Confidence |
|---|---|---|---|---|---|
| YYYY-MM-DD | <本 ADR 主題> | A / B | A | B (成本 > 收益) | **[H]** |
---
## 12. Confidence & Sources & TODO
- **整份文件最低 confidence 欄位：** <列出所有 [L] 與 [M]>
- **Fabricated assumptions（推測但 input 未明說）：**
- <假設 1>
- **Highest-value next input:** <下一份最該補的資料：benchmark / spike / interview>
### TODO（缺資料）
- _TODO: 需要 spike 驗證 Option A 在 X scale 下的可用性_
---
> [!CAUTION]
> **輸出前 AI 自檢：**
> - [ ] 6 段 H2 章節齊全（編號 1, 2, 3, 6, 10, 12，刻意不連號）
> - [ ] Options ≥ 2 個，每個含 pros + cons
> - [ ] Decision 段含 negative consequences（必填）
> - [ ] 每個 chosen 帶 inline `[H/M/L]` badge
> - [ ] Decision Log ≥ 1 條，每條有 rejected reason
> - [ ] 單一決策原子文件（input 含多決策應拆多份）
> - [ ] 無 YAML / JSON schema 輸出（ADR 是給人讀的 markdown）Practice · 換你試做
先用自己的話交代素材，不需要先學會工程術語
確定的就寫，不確定的留白。下一步要做的是請 Agent 找缺口，不是讓它替你猜一套合理答案。
可以先留白；複製提示詞後再到 Coding Agent 裡補充。
AI Practice · 手動三步
先問、再寫、最後審，不把整條流程鎖死
每一步都是獨立工作包。你可以停下補資料、修改限制或重做某一步，不需要服從固定的 Agent 接力流程。
只找阻擋文件成立的未知
先補會改變範圍、判斷或驗收結果的資訊，不急著寫文件。
我要製作「ADR · 架構決策紀錄」。先不要產出文件。
請根據我的素材，找出會影響這份文件正確性或可執行性的未知事項，一次最多問 5 題。
每題請包含：
1. 問題
2. 為什麼現在必須知道
3. 它會影響哪個章節或決定
已經回答的事不要重問；可以延後的事標成「待決策」；不要替我猜答案。
本文件的核心章節：Context、Decision Drivers、Options Considered、Decision & Consequences、Decision Log、Confidence & Sources & TODO複製後，請在標示位置貼上自己的素材。
Review · 自己驗收
文件存在，不代表下一個角色真的能使用
逐條檢查 Agent 的輸出。人類負責需求、限制與驗收，也必須能說明重要結論從哪裡來。
帶著這份文件，繼續到「C4 圖 · 四層架構視圖」
下一張卡會接住新的決策問題；不用一次把整條 SDLC 全做完。