Architecture Decision Record。アーキテクチャ上の重要な意思決定と、その背景・トレードオフ・結果を記録する軽量なドキュメント。 Michael Nygard が2011年のブログ記事で提唱した。
なぜ書くのか¶
「なぜこの設計にしたか」が数ヶ月後には失われる：コードは「何をしているか」を示すが、「なぜそうしたか」「他に何を検討し、 なぜ却下したか」は残らない
意思決定の手戻りを防ぐ：過去に検討済みのトレードオフを知らずに同じ議論を繰り返すことを防げる
オンボーディングの助けになる：新しく参加したメンバーが設計の背景を短時間で追える
アーキテクチャ特性 の選択のように、複数のトレードオフの中から1つを選ぶ判断ほどADRの効果が大きい。
テンプレート¶
決まった形式はないが、Nygardが示した基本形は以下のようにシンプル。
# ADR-0012: 注文サービスのデータストアにPostgreSQLを採用する
## ステータス
承認済み（2024-03-01）
## コンテキスト
注文サービスは強い整合性とトランザクションが必要。読み取り負荷は中程度で、将来的なスケールアウトよりも
まず正確性を優先したい。
## 決定
PostgreSQLを採用する。
## 検討した代替案
- DynamoDB: スケーラビリティは高いが、複雑なトランザクションの表現がしづらい
- MongoDB: スキーマ柔軟性はメリットだが、注文ドメインは構造が安定しておりRDBMSの制約の方が有用
## 結果
- Pros: 強い整合性、成熟したツール群、チームの知見が豊富
- Cons: 将来的に書き込みが急増した場合はシャーディング戦略の追加検討が必要各ADRは一度書いたら基本的に変更しない（Immutable）。決定が覆った場合は、古いADRを「Superseded」にして、
新しいADRを追加する形で記録を積み重ねる。番号を振って docs/adr/0001-xxx.md のように連番ファイルで管理することが多い。
書くべき判断・書かなくてよい判断¶
書く価値があるのは、覆すコストが高い決定：
データストアやメッセージングミドルウェアの選定
サービス分割の境界（境界づけられたコンテキスト の決定）
認証・認可方式のような、後から変えると影響範囲が広い横断的関心事
逆に、ローカルな実装の詳細（変数名、1関数内のロジック）はコードコメントやPRの説明で十分で、ADRにする必要はない。