<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>ADR on Eric 個人部落格</title><link>https://chihhung.github.io/Blog/tags/adr/</link><description>Recent content in ADR on Eric 個人部落格</description><generator>Hugo</generator><language>zh-TW</language><lastBuildDate>Tue, 06 Oct 2026 00:00:00 +0000</lastBuildDate><atom:link href="https://chihhung.github.io/Blog/tags/adr/index.xml" rel="self" type="application/rss+xml"/><item><title>架構決策紀錄範本（ADR, Architecture Decision Record Template）</title><link>https://chihhung.github.io/Blog/posts/%E6%95%99%E5%AD%B8/templates/design/adr_template/</link><pubDate>Tue, 06 Oct 2026 00:00:00 +0000</pubDate><guid>https://chihhung.github.io/Blog/posts/%E6%95%99%E5%AD%B8/templates/design/adr_template/</guid><description>&lt;h1 id="架構決策紀錄範本architecture-decision-record-adr"&gt;架構決策紀錄範本（Architecture Decision Record, ADR）&lt;/h1&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;參照標準&lt;/strong&gt;：MADR 4.0.0（Markdown Architectural Decision Records）/ ISO/IEC/IEEE 42010:2022&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;文件用途&lt;/strong&gt;：記錄一個重要技術決策的背景、考慮過的選項、取捨與後果&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;適用階段&lt;/strong&gt;：系統設計階段（Design Phase）起，貫穿整個生命週期&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;範本版本&lt;/strong&gt;：v2.0（2026-10-06）｜對應《軟體開發標準程序教學手冊》v2.0 第 4.6 節&lt;/p&gt;&lt;/blockquote&gt;
&lt;hr&gt;
&lt;h2 id="-章節目錄"&gt;📋 章節目錄&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;a href="#1-%E4%BD%95%E6%99%82%E5%BF%85%E9%A0%88%E5%AF%AB-adr"&gt;何時必須寫 ADR&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="#2-%E6%AA%94%E6%A1%88%E5%91%BD%E5%90%8D%E8%88%87%E5%AD%98%E6%94%BE"&gt;檔案命名與存放&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="#3-adr-%E4%B8%BB%E9%AB%94madr-%E6%A0%BC%E5%BC%8F"&gt;ADR 主體（MADR 格式）&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="#4-%E7%8B%80%E6%85%8B%E8%88%87%E7%94%9F%E5%91%BD%E9%80%B1%E6%9C%9F"&gt;狀態與生命週期&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="#5-%E5%AF%A9%E6%9F%A5%E8%88%87%E9%A9%97%E8%AD%89"&gt;審查與驗證&lt;/a&gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;hr&gt;
&lt;h2 id="1-何時必須寫-adr"&gt;1. 何時必須寫 ADR&lt;/h2&gt;
&lt;h3 id="-範本"&gt;📝 範本&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;情境&lt;/th&gt;
&lt;th&gt;是否必須寫 ADR&lt;/th&gt;
&lt;th&gt;本案判定&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;選用或更換框架、資料庫、訊息系統&lt;/td&gt;
&lt;td&gt;必須&lt;/td&gt;
&lt;td&gt;{是／否}&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;改變系統間的整合方式（同步改非同步、新增閘道）&lt;/td&gt;
&lt;td&gt;必須&lt;/td&gt;
&lt;td&gt;{是／否}&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;偏離公司標準或《軟體開發標準程序教學手冊》&lt;/td&gt;
&lt;td&gt;必須&lt;/td&gt;
&lt;td&gt;{是／否}&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;難以反悔（回頭成本高）的決策&lt;/td&gt;
&lt;td&gt;必須&lt;/td&gt;
&lt;td&gt;{是／否}&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;只影響單一類別的實作細節&lt;/td&gt;
&lt;td&gt;不需要&lt;/td&gt;
&lt;td&gt;{是／否}&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3 id="-使用說明"&gt;📖 使用說明&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;ADR 是「決策的快照」，回答半年後有人問「為什麼當初這樣做？」&lt;/li&gt;
&lt;li&gt;判斷原則：如果這個決策錯了，修正成本是否超過一個 Sprint？是 → 寫 ADR&lt;/li&gt;
&lt;li&gt;ADR 要短（一到兩頁），長篇設計放在 SDD，ADR 只記錄決策本身&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id="-範例"&gt;💡 範例&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;情境&lt;/th&gt;
&lt;th&gt;是否必須寫 ADR&lt;/th&gt;
&lt;th&gt;本案判定&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;請假事件通知由同步 REST 改為 Kafka 事件&lt;/td&gt;
&lt;td&gt;必須&lt;/td&gt;
&lt;td&gt;是 → ADR-0007&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;請假服務的 DTO 改用 Java record&lt;/td&gt;
&lt;td&gt;不需要&lt;/td&gt;
&lt;td&gt;否（屬《程式寫作指引》範圍）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;hr&gt;
&lt;h2 id="2-檔案命名與存放"&gt;2. 檔案命名與存放&lt;/h2&gt;
&lt;h3 id="-範本-1"&gt;📝 範本&lt;/h3&gt;
&lt;div class="highlight"&gt;
&lt;pre tabindex="0"&gt;&lt;code class="language-text" data-lang="text"&gt;docs/decisions/
├── 0001-{決策標題-kebab-case}.md
├── 0002-{決策標題}.md
└── README.md # ADR 索引：編號、標題、狀態、日期&lt;/code&gt;&lt;/pre&gt;
&lt;/div&gt;
&lt;h3 id="-使用說明-1"&gt;📖 使用說明&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;ADR 與程式碼放在同一個 Repository，走同一個 PR 審查流程（Docs-as-Code）&lt;/li&gt;
&lt;li&gt;編號遞增、不重用；標題用動詞開頭描述決策（例：「採用 Kafka 作為訂單事件骨幹」）&lt;/li&gt;
&lt;li&gt;索引檔讓新人快速找到所有決策&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id="-範例-1"&gt;💡 範例&lt;/h3&gt;
&lt;div class="highlight"&gt;
&lt;pre tabindex="0"&gt;&lt;code class="language-text" data-lang="text"&gt;docs/decisions/
├── 0001-use-postgresql-as-primary-database.md
├── 0006-adopt-rfc9457-problem-details.md
├── 0007-use-kafka-for-leave-events.md
└── README.md&lt;/code&gt;&lt;/pre&gt;
&lt;/div&gt;
&lt;hr&gt;
&lt;h2 id="3-adr-主體madr-格式"&gt;3. ADR 主體（MADR 格式）&lt;/h2&gt;
&lt;h3 id="-範本-2"&gt;📝 範本&lt;/h3&gt;
&lt;div class="highlight"&gt;
&lt;pre tabindex="0"&gt;&lt;code class="language-markdown" data-lang="markdown"&gt;---
status: {proposed | accepted | rejected | deprecated | superseded by NNNN}
date: {YYYY-MM-DD}
decision-makers: {決策者姓名與角色}
consulted: {諮詢對象}
informed: {知會對象}
---
# {NNNN} {決策標題}
## Context and Problem Statement
{兩到三句描述背景與要解決的問題；可附事件編號、數據}
## Decision Drivers
* {驅動因素 1，例：下游故障不得影響主流程}
* {驅動因素 2，例：尖峰 N 筆/秒}
## Considered Options
* {選項 1}
* {選項 2}
* {選項 3（含「維持現狀」）}
## Decision Outcome
選擇「{選項}」，因為 {對照 Decision Drivers 說明理由}。
### Consequences
* Good：{正面影響}
* Bad：{負面影響與需要處理的新問題}
### Confirmation
{如何確認決策被正確實作，例：整合測試、ArchUnit 規則、上線後監控指標}
## Pros and Cons of the Options
### {選項 2}
* Good：{優點}
* Bad：{缺點}&lt;/code&gt;&lt;/pre&gt;
&lt;/div&gt;
&lt;h3 id="-使用說明-2"&gt;📖 使用說明&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;必填段落：Context、Considered Options（至少兩個，含「維持現狀」）、Decision Outcome、Consequences&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Bad 後果必須寫&lt;/strong&gt;：沒有缺點的決策通常代表分析不完整&lt;/li&gt;
&lt;li&gt;Confirmation 段落讓決策可驗證，例如用 ArchUnit 測試確保「訂單服務不得直接呼叫點數服務」&lt;/li&gt;
&lt;li&gt;引用的效能數據、事件編號需可查證&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id="-範例-2"&gt;💡 範例&lt;/h3&gt;
&lt;div class="highlight"&gt;
&lt;pre tabindex="0"&gt;&lt;code class="language-markdown" data-lang="markdown"&gt;---
status: accepted
date: 2026-09-20
decision-makers: 架構師 林志明、Tech Lead 陳大文
consulted: DBA 王小美、資安 李小華
informed: HRMS 開發團隊
---
# 0007 請假事件改用 Kafka 通知下游
## Context and Problem Statement
請假核准後需通知薪資、出勤、Email 三個服務。目前以同步 REST 呼叫，
2026 Q3 薪資服務維護期間造成請假核准失敗 3 次（INC-20260712-002）。
## Decision Drivers
* 下游服務故障不得影響請假核准
* 事件需可重播 7 天，以便薪資重算
* 維運團隊已有 Kafka 叢集與維運經驗
## Considered Options
* Apache Kafka
* RabbitMQ
* 維持同步 REST &amp;#43; 重試
## Decision Outcome
選擇 Apache Kafka，因為它是唯一同時滿足「下游故障不影響核准」與「事件可重播 7 天」的選項，且不需新增維運技能。
### Consequences
* Good：下游故障不再影響核准；新服務可自行訂閱事件
* Bad：事件可能重複投遞，消費端必須冪等；需監控 consumer lag
### Confirmation
整合測試驗證「薪資服務停止時仍可核准請假」；上線後監控 consumer lag &amp;lt; 1,000。
## Pros and Cons of the Options
### RabbitMQ
* Good：團隊熟悉 AMQP 路由
* Bad：訊息消費後即刪除，不支援 7 天重播
### 維持同步 REST &amp;#43; 重試
* Good：不需新元件
* Bad：重試會延長核准回應時間，且下游長時間故障時仍會失敗&lt;/code&gt;&lt;/pre&gt;
&lt;/div&gt;
&lt;hr&gt;
&lt;h2 id="4-狀態與生命週期"&gt;4. 狀態與生命週期&lt;/h2&gt;
&lt;h3 id="-範本-3"&gt;📝 範本&lt;/h3&gt;
&lt;pre class="mermaid"&gt;stateDiagram-v2
[*] --&amp;gt; proposed: 提出
proposed --&amp;gt; accepted: 審查通過
proposed --&amp;gt; rejected: 審查否決
accepted --&amp;gt; deprecated: 不再適用
accepted --&amp;gt; superseded: 被新 ADR 取代
rejected --&amp;gt; [*]
deprecated --&amp;gt; [*]
superseded --&amp;gt; [*]&lt;/pre&gt;
&lt;h3 id="-使用說明-3"&gt;📖 使用說明&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;ADR 一經 &lt;code&gt;accepted&lt;/code&gt; 就&lt;strong&gt;不修改內容&lt;/strong&gt;（錯字除外）；決策改變時新增一份 ADR，舊 ADR 的 &lt;code&gt;status&lt;/code&gt; 改為 &lt;code&gt;superseded by NNNN&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;rejected&lt;/code&gt; 的 ADR 也要保留，避免同樣的提案反覆討論&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id="-範例-3"&gt;💡 範例&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;編號&lt;/th&gt;
&lt;th&gt;標題&lt;/th&gt;
&lt;th&gt;狀態&lt;/th&gt;
&lt;th&gt;日期&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;0003&lt;/td&gt;
&lt;td&gt;請假通知使用同步 REST&lt;/td&gt;
&lt;td&gt;superseded by 0007&lt;/td&gt;
&lt;td&gt;2025-11-02&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0007&lt;/td&gt;
&lt;td&gt;請假事件改用 Kafka 通知下游&lt;/td&gt;
&lt;td&gt;accepted&lt;/td&gt;
&lt;td&gt;2026-09-20&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;hr&gt;
&lt;h2 id="5-審查與驗證"&gt;5. 審查與驗證&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;本節供審查者使用，也用來檢查 AI 依本範本產出的 ADR 是否正確。&lt;/p&gt;</description></item></channel></rss>