架構決策紀錄範本(ADR, Architecture Decision Record Template)

架構決策紀錄範本(Architecture Decision Record, ADR) 參照標準:MADR 4.0.0(Markdown Architectural Decision Records)/ ISO/IEC/IEEE 42010:2022 文件用途:記錄一個重要技術決策的背景、考慮過的選項、取捨與後果 適用階段:系統設計階段(Design Phase)起,貫穿整個生命週期 範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 4.6 節 📋 章節目錄 何時必須寫 ADR 檔案命名與存放 ADR 主體(MADR 格式) 狀態與生命週期 審查與驗證 1. 何時必須寫 ADR 📝 範本 情境 是否必須寫 ADR 本案判定 選用或更換框架、資料庫、訊息系統 必須 {是/否} 改變系統間的整合方式(同步改非同步、新增閘道) 必須 {是/否} 偏離公司標準或《軟體開發標準程序教學手冊》 必須 {是/否} 難以反悔(回頭成本高)的決策 必須 {是/否} 只影響單一類別的實作細節 不需要 {是/否} 📖 使用說明 ADR 是「決策的快照」,回答半年後有人問「為什麼當初這樣做?」 判斷原則:如果這個決策錯了,修正成本是否超過一個 Sprint?是 → 寫 ADR ADR 要短(一到兩頁),長篇設計放在 SDD,ADR 只記錄決策本身 💡 範例 情境 是否必須寫 ADR 本案判定 請假事件通知由同步 REST 改為 Kafka 事件 必須 是 → ADR-0007 請假服務的 DTO 改用 Java record 不需要 否(屬《程式寫作指引》範圍) 2. 檔案命名與存放 📝 範本 docs/decisions/ ├── 0001-{決策標題-kebab-case}.md ├── 0002-{決策標題}.md └── README.md # ADR 索引:編號、標題、狀態、日期 📖 使用說明 ADR 與程式碼放在同一個 Repository,走同一個 PR 審查流程(Docs-as-Code) 編號遞增、不重用;標題用動詞開頭描述決策(例:「採用 Kafka 作為訂單事件骨幹」) 索引檔讓新人快速找到所有決策 💡 範例 docs/decisions/ ├── 0001-use-postgresql-as-primary-database.md ├── 0006-adopt-rfc9457-problem-details.md ├── 0007-use-kafka-for-leave-events.md └── README.md 3. ADR 主體(MADR 格式) 📝 範本 --- 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:{缺點} 📖 使用說明 必填段落:Context、Considered Options(至少兩個,含「維持現狀」)、Decision Outcome、Consequences Bad 後果必須寫:沒有缺點的決策通常代表分析不完整 Confirmation 段落讓決策可驗證,例如用 ArchUnit 測試確保「訂單服務不得直接呼叫點數服務」 引用的效能數據、事件編號需可查證 💡 範例 --- 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 + 重試 ## Decision Outcome 選擇 Apache Kafka,因為它是唯一同時滿足「下游故障不影響核准」與「事件可重播 7 天」的選項,且不需新增維運技能。 ### Consequences * Good:下游故障不再影響核准;新服務可自行訂閱事件 * Bad:事件可能重複投遞,消費端必須冪等;需監控 consumer lag ### Confirmation 整合測試驗證「薪資服務停止時仍可核准請假」;上線後監控 consumer lag < 1,000。 ## Pros and Cons of the Options ### RabbitMQ * Good:團隊熟悉 AMQP 路由 * Bad:訊息消費後即刪除,不支援 7 天重播 ### 維持同步 REST + 重試 * Good:不需新元件 * Bad:重試會延長核准回應時間,且下游長時間故障時仍會失敗 4. 狀態與生命週期 📝 範本 stateDiagram-v2 [*] --> proposed: 提出 proposed --> accepted: 審查通過 proposed --> rejected: 審查否決 accepted --> deprecated: 不再適用 accepted --> superseded: 被新 ADR 取代 rejected --> [*] deprecated --> [*] superseded --> [*] 📖 使用說明 ADR 一經 accepted 就不修改內容(錯字除外);決策改變時新增一份 ADR,舊 ADR 的 status 改為 superseded by NNNN rejected 的 ADR 也要保留,避免同樣的提案反覆討論 💡 範例 編號 標題 狀態 日期 0003 請假通知使用同步 REST superseded by 0007 2025-11-02 0007 請假事件改用 Kafka 通知下游 accepted 2026-09-20 5. 審查與驗證 本節供審查者使用,也用來檢查 AI 依本範本產出的 ADR 是否正確。 ...

October 6, 2026 · 3 min · 492 words · Eric Cheng

SAD 系統架構文件範本(System Architecture Document Template)

SAD 系統架構文件範本(System Architecture Document) 參照標準:ISO/IEC/IEEE 42010:2022(取代 IEEE 1471-2000) 文件用途:描述系統架構決策、觀點、視圖與品質屬性,作為開發團隊的設計藍圖 適用階段:系統設計階段(System Design Phase) 範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 4.1、4.2、4.6、4.7 節 📋 章節目錄 文件資訊 架構概述 架構利害關係人與關注點 架構觀點定義 邏輯視圖 開發視圖 部署視圖 流程視圖 資料架構視圖 架構決策記錄 品質屬性與戰術 安全架構 附錄 審查與驗證 1. 文件資訊 📝 範本 項目 內容 文件編號 SAD-{專案代碼}-{序號} 文件名稱 {系統名稱} 系統架構文件 版本 v{主版本}.{次版本} 狀態 草稿 / 審核中 / 核定 建立日期 {YYYY-MM-DD} 最後更新 {YYYY-MM-DD} 架構師 {姓名} 審核者 {姓名/角色} 對應 FRD {FRD 文件編號} 版本歷程 版本 日期 修改人 修改內容摘要 v0.1 {YYYY-MM-DD} {姓名} 初版架構設計 📖 使用說明 依據 ISO/IEC/IEEE 42010:2022 第 5.1 節,架構描述應包含識別資訊 SAD 承接 FRD,將功能需求與非功能需求轉化為架構設計方案 架構文件是「活文件」(Living Document),隨設計演進持續更新 💡 範例 項目 內容 文件編號 SAD-HRM-001 文件名稱 人力資源管理系統 系統架構文件 版本 v1.3 架構師 陳建築 對應 FRD FRD-HRM-001 v2.1 2. 架構概述 📝 範本 2.1 系統背景(System Context) {描述系統在組織 IT 環境中的定位} ...

May 18, 2026 · 8 min · 1649 words · Eric Cheng

架構轉換專案計畫範本

📝 專案計畫書範本(草稿) 1. 專案簡介 專案名稱:應用系統架構轉型計畫 專案目標: Phase 1:單體 → 容器化 → 上雲,達成 Lift & Shift Phase 2:單體 → 微服務 → 容器化 → 上雲,完成業務導向解耦 範圍: 涉及核心應用(XX 系統)、資料庫(DB2 / Oracle)、應用伺服器(Liberty)、批次處理(Spring Batch) 預期效益: 部署時間縮短 70% MTTR 減少 50% 系統彈性與可擴展性提升 2. 專案里程碑 (Milestones) 里程碑 說明 產出物 時間 負責角色 M1 現況盤點與架構審視 系統盤點報告、風險清單 W1–W2 架構師、系統分析師 M2 容器化樣板建立 Dockerfile、Helm Chart、CI/CD Pipeline W3–W4 DevOps 工程師 M3 雲網路與基礎建設就緒 Terraform 模組、網路拓樸、資安控管表 W5–W6 雲平台工程師 M4 容器化驗證 SIT 測試報告、壓測報告、回退計畫 W7–W8 測試團隊、SRE M5 首批系統上線 上線計畫、Runbook、SLA/SLO 報告 W9–W10 PM、應用團隊 M6 微服務設計完成 業務域切分、API 契約、事件流設計 P2 W1–W2 架構師、業務分析師 M7 第一波微服務上線 新服務、契約測試、金絲雀報告 P2 W5–W8 Dev 團隊、SRE M8 單體功能替換完成 Strangler 完成報告、單體下線 P2 W12+ 架構師、PM 3. RACI 表(責任分配矩陣) 活動 PM 架構師 Dev DevOps/SRE 測試 業務單位 現況盤點 A R C C C I 容器化設計 C A/R R C I I CI/CD Pipeline I C R A I I 雲網路與 IaC I C I A/R I I SIT/UAT 測試 C C R C A I 上線與回退 A R R R C I 微服務切分 C A/R R C I C API/事件治理 I A R C C C 營運/Runbook A C I R I I (A=Accountable 負責決策 / R=Responsible 執行 / C=Consulted 諮詢 / I=Informed 知會) ...

October 31, 2025 · 2 min · 243 words · Eric Cheng

架構轉換專案計畫範本

📝 專案計畫書範本(草稿) 1. 專案簡介 專案名稱:應用系統架構轉型計畫 專案目標: Phase 1:單體 → 容器化 → 上雲,達成 Lift & Shift Phase 2:單體 → 微服務 → 容器化 → 上雲,完成業務導向解耦 範圍: 涉及核心應用(XX 系統)、資料庫(DB2 / Oracle)、應用伺服器(Liberty)、批次處理(Spring Batch) 預期效益: 部署時間縮短 70% MTTR 減少 50% 系統彈性與可擴展性提升 2. 專案里程碑 (Milestones) 里程碑 說明 產出物 時間 負責角色 M1 現況盤點與架構審視 系統盤點報告、風險清單 W1–W2 架構師、系統分析師 M2 容器化樣板建立 Dockerfile、Helm Chart、CI/CD Pipeline W3–W4 DevOps 工程師 M3 雲網路與基礎建設就緒 Terraform 模組、網路拓樸、資安控管表 W5–W6 雲平台工程師 M4 容器化驗證 SIT 測試報告、壓測報告、回退計畫 W7–W8 測試團隊、SRE M5 首批系統上線 上線計畫、Runbook、SLA/SLO 報告 W9–W10 PM、應用團隊 M6 微服務設計完成 業務域切分、API 契約、事件流設計 P2 W1–W2 架構師、業務分析師 M7 第一波微服務上線 新服務、契約測試、金絲雀報告 P2 W5–W8 Dev 團隊、SRE M8 單體功能替換完成 Strangler 完成報告、單體下線 P2 W12+ 架構師、PM 3. RACI 表(責任分配矩陣) 活動 PM 架構師 Dev DevOps/SRE 測試 業務單位 現況盤點 A R C C C I 容器化設計 C A/R R C I I CI/CD Pipeline I C R A I I 雲網路與 IaC I C I A/R I I SIT/UAT 測試 C C R C A I 上線與回退 A R R R C I 微服務切分 C A/R R C I C API/事件治理 I A R C C C 營運/Runbook A C I R I I (A=Accountable 負責決策 / R=Responsible 執行 / C=Consulted 諮詢 / I=Informed 知會) ...

October 31, 2025 · 2 min · 243 words · Eric Cheng