ADR（Architecture Decision Records）

Posted on

什麼是 ADR？

  • Architecture Decision Records（ADR，架構決策紀錄）是 ThoughtWorks 推廣的一種輕量文件，用來記錄：「我們為什麼在當時做了這個架構決定」
  • 是決策的歷史紀錄
  • ADR 記的是「選擇」，不是「結果」。

ADR 解決什麼問題？

  • 記錄當下是如何做決策的，供未來參考
  • 避免未來的自己心中冒出：「當初是在想什麼？」的疑問
  • 一個決策一頁，10 分鐘寫完

一份 ADR 的基本結構

  1. Title
    用一句話說決定是什麼
  2. Status
    • Proposed（提案）
    • Accepted
    • Deprecated
    • Superseded（被取代）
  3. Context（背景）
    問題是什麼？限制是什麼？
  4. Decision
    決定怎麼做
  5. Consequences
    好處、壞處、風險、未來影響

Markdown Template

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# System ADR-N Title

## Status

Proposed（提案）/ Accepted / Deprecated / Superseded（被取代）

## Context



## Decision



## Consequences



## Related Resources (optional)



---


什麼時候值得寫 ADR？

有以下情況之一就值得寫：

  • 有取捨
  • 有爭議
  • 未來可能後悔
  • 未來的自己可能會問「為什麼」

Refs