アーキテクチャ レッスン6
アーキテクチャ決定とADR
重要な設計判断とその理由を記録するArchitecture Decision Record(ADR)の書き方と活用法を学ぶ
なぜ意思決定を記録するのか
「なぜこのフレームワークを選んだのか」「なぜマイクロサービス化を見送ったのか」といった判断は、 時間が経つと当事者の記憶からも薄れていきます。新しく参加したメンバーは、その経緯を知らないまま 「今のコードは変えられない前提」として扱ってしまったり、逆に既に検討済みの案を再提案してしまったりします。
ADR(Architecture Decision Record)は、 こうした重要な設計判断を短い文書として記録し、後から誰でも経緯を追えるようにする手法です。
ADRの基本構成
ADRには様々な流儀がありますが、代表的なテンプレートは次の3要素(+タイトルとステータス)です。
# ADR-0007: 注文サービスのデータストアにPostgreSQLを採用する
## Status(状態)
Accepted (承認済み) — 2026-03-01
## Context(背景)
注文サービスは強い整合性が求められる決済関連の書き込みが多く、
複雑な結合クエリでの集計要件もある。チームはリレーショナルDBの運用経験が豊富。
候補として PostgreSQL / MongoDB / DynamoDB を比較した。
## Decision(決定内容)
注文サービスのプライマリデータストアとして PostgreSQL を採用する。
## Consequences(結果として生じる影響)
- 良い面: トランザクション整合性が確保しやすい。チームの学習コストが低い。
- 悪い面: 将来的に書き込みが急増した場合、水平シャーディングの設計コストが発生する。
- 対応: 半年後にスループットを再計測し、必要ならシャーディング導入を再検討する ADR を書く。重要なのは「何を選んだか」だけでなく、「他にどんな選択肢があり、なぜそれを選ばなかったか」 「この決定によってどんな悪い面を引き受けることになるか」まで書くことです。
ADRを書くタイミングと運用
書くべきタイミング
採用技術の選定、サービス分割の判断、大規模なデータモデルの変更など、後から覆すコストが高い決定を行った直後
保管場所
リポジトリ内に docs/adr/ のようなディレクトリを作り、コードと一緒にバージョン管理する運用が広く使われている
状態の変化
決定が後から覆った場合は元のADRを削除せず、Status を Superseded(後継あり)にして新しいADRへのリンクを残す
良いADRの条件
- 1つのADRは1つの決定だけを扱い、短く読み切れる分量にする
- 検討した他の選択肢と、それを採らなかった理由も残す
- 良い影響だけでなく、引き受けることになる悪い影響も正直に書く
- 後から見返す人が前提知識ゼロでも文脈を理解できるように書く
ポイント
- ADRはContext(背景)・Decision(決定内容)・Consequences(結果として生じる影響)を軸に記録する
- 覆すコストの高い重要な決定を行った直後に、その都度書くのが基本
- 良い面だけでなく代償も正直に書き、決定が覆った場合はSupersededとして履歴を残す
確認クイズ
1 / 3ADR(Architecture Decision Record)を書く主な目的として適切なものはどれか？