数か月後に「なぜこのデータベースを選んだのか」と聞かれ、誰も答えられないことがあります。コードから現在の構造は読めても、当時の予算、期限、候補、却下理由までは読み取れません。その空白を埋めるのが意思決定記録です。
意思決定記録は正解を証明する文書ではなく、その時点の前提でなぜ妥当と判断したかを未来へ渡す文書です。
定義と結論
Architecture Decision Record（ADR）は、アーキテクチャ上重要な一つの決定と、その背景・選択肢・結果を短く残す記録です。複数のADRを時系列で集めたものはArchitecture Decision Logと呼ばれます。
ADRの価値は採用技術の一覧ではなく、判断の文脈にあります。「PostgreSQLを使う」だけでは、要件が変わった時に再評価できません。「整合性が必要な注文処理で、運用経験と予算を踏まえて採用した」と残せば、前提が変わったかを比較できます。
結論として、後から覆すコストが高い決定、複数人へ影響する決定、何度も議論になりそうな決定を、一件一ファイルで簡潔に記録します。
なぜ必要なのか
口頭の合意やチャットは流れます。会議録は発言の順番を残しても、最終的な決定と理由が埋もれがちです。コードコメントは実装の近くに置けますが、複数サービスにまたがる比較や事業上の制約には向きません。
記録があると、新メンバーは過去の議論を再演せずに現在地を理解できます。障害時には設計上受け入れた不利益を確認でき、置き換え時には当時の候補と見直し条件から再検討を始められます。
記録しないコストは、同じ議論の繰り返しと、失われた前提を想像で補う危険として後から現れます。
誰が書き、誰が読むか
提案者が最初の草案を書き、影響を受ける開発者、運用担当、セキュリティ担当、プロダクト責任者が必要な観点を確認します。最終決定者はチームの責任分界に従います。全員一致をADRの必須条件にすると止まりやすいため、反対意見と採用しなかった理由も結果に残します。
主な読者は、実装者、レビュー担当者、将来の保守担当者、新しく参加するメンバーです。したがって、会議に出た人だけが分かる略語や「先日の件」のような参照は避けます。
何を記録するか
最小構成は次のとおりです。
| 項目 | 書く内容 |
|---|---|
| 題名 | 決定を能動形で短く表す |
| 状態 | 提案中、採用、却下、置換など |
| 背景 | 解決する問題、制約、判断時点の事実 |
| 選択肢 | 真剣に比較した案と「何もしない」案 |
| 決定 | 採用案と、その理由 |
| 結果 | 利点、不利益、追加作業、リスク |
| 見直し条件 | 再評価を始める観測可能な条件 |
日付、決定者、関連IssueやPull Requestも追跡に役立ちます。ただし、項目を増やして書かれなくなるなら最小構成を優先します。
記録する流れ
1. 決定の境界を一つに絞る
「新システムの設計」のような大題ではなく、「画像保存先にオブジェクトストレージを使う」のようにします。認証方式と画像保存を一つのADRに混ぜると、片方だけ変更しにくくなります。
2. 決定前の事実を書く
背景には結論を正当化する文章ではなく、問題と制約を書きます。「サーバーの再配置でローカルファイルが消える」「月額上限がある」「公開URLが必要」のように検証可能な表現にします。
3. 比較軸を先に決める
費用、信頼性、性能、セキュリティ、運用経験、移行容易性など、今回重要な軸を決めます。候補ごとに都合のよい軸を変えてはいけません。
4. 採用しない案も公平に残す
候補の欠点だけを並べて採用案を勝たせるのではなく、それぞれの利点と不利益を書きます。「何もしない」案も、現状維持の費用を見えるようにします。
5. 決定と結果を分ける
決定は何を選ぶか、結果は選んだことで生じる影響です。設定や監視が増えるなどの負の結果も隠しません。
6. 採用後は書き換えず、置換する
前提が変わったら過去のADRを削除せず、新しいADRから「置換」として参照します。履歴が残ることで、判断が変わった理由を追えます。
具体例：画像保存先を決める
# ADR-0007: 画像をオブジェクトストレージへ保存する
- 状態: 採用
- 日付: 2026-07-11
## 背景
アプリサーバーは再配置され、ローカルファイルは永続化されない。
画像には公開URLとバックアップが必要で、月額予算に上限がある。
## 選択肢
- ローカルディスク: 実装は単純だが再配置で失われる
- データベース: 一貫したバックアップが可能だがDB負荷が増える
- オブジェクトストレージ: 設定は増えるが容量と配信を分離できる
## 決定
オブジェクトストレージを採用する。
## 結果
署名URL、権限、削除処理、監視の実装が必要になる。
## 見直し条件
月間保存量または転送費が予算上限を継続して超えた時。
この例では「クラウドだから」という曖昧な理由を避け、永続化、配信、予算という比較軸を示しています。負の結果まで書くと、実装タスクと運用上の注意が見えるようになります。
他の文書との違い
| 文書 | 主な目的 | ADRとの関係 |
|---|---|---|
| 会議録 | 発言、議題、宿題を残す | 決定に至る議論の資料 |
| 設計書 | 現在の構造や振る舞いを説明 | ADRの結果を反映する |
| README | 導入・利用・開発方法を案内 | 重要ADRへの入口を置ける |
| Issue | 作業と進捗を管理 | ADR作成・実装を追跡する |
| コードコメント | 局所的な意図を説明 | 実装近くからADRを参照できる |
ADRですべてを説明しようとせず、詳細な性能測定や脅威分析は別資料に置き、安定したリンクで参照します。
どの決定を残すべきか
フレームワーク、データ保存、認証、外部API、デプロイ方式、公開インターフェース、依存関係の方針などは候補です。一方、容易に戻せる命名や一時的な実装詳細まで記録すると、重要な決定が埋もれます。
判断に迷ったら、次の質問を使います。
- 間違えた時の変更費用は高いか
- 複数のチームや長期間に影響するか
- 妥当な選択肢が複数あり、理由がコードだけでは分からないか
- 半年後に同じ議論が起きそうか
二つ以上当てはまるなら記録する価値があります。
よくある誤解
「ADRは大規模組織だけのもの」
一人開発でも、未来の自分は当時の文脈を忘れます。小規模なら数段落で十分です。
「採用後は変更してはいけない」
ADRは永久ルールではありません。前提が変われば新しい判断で置換します。過去の記録を消さないことが重要です。
「比較表の点数が最適解を出す」
点数は議論を整理しますが、重み付け自体が判断です。数字を客観性の証明として扱わず、根拠を併記します。
「長いほど丁寧」
読まれない記録は役に立ちません。結論と理由を冒頭で把握でき、詳細へリンクできる長さが適切です。
注意点とベストプラクティス
- リポジトリで連番または日付を使い、命名規則を統一する
- 一件一決定にし、レビュー可能な差分で追加する
- 秘密情報、個人情報、非公開の認証情報を書かない
- 「高速」「安い」ではなく測定値、上限、条件を書く
- 採用案に不利な結果も記録する
- 状態と置換先を更新し、本文の歴史は改ざんしない
- 関連するコード、Issue、運用手順から相互リンクする
確認・デバッグ方法
ADR自体も品質確認できます。題名だけで決定が分かるか、背景に結論が混ざっていないか、比較軸が候補間で同じか、負の結果と見直し条件があるかをレビューします。リンク切れ、重複番号、存在しない置換先はCIで機械的に検査できます。
実装後は、コードとADRが一致するか確認します。たとえばオブジェクトストレージ採用ADRがあるのにローカル保存が残っていれば、移行途中なのか逸脱なのかを判断します。障害や費用超過が見直し条件に達したら、新しいADRを提案します。
ADRのデバッグとは文章の誤字確認だけでなく、記録した前提と現実がまだ一致しているかを確かめることです。
まとめ
意思決定記録は、決定、背景、選択肢、結果、見直し条件を短く残す仕組みです。重要な一決定に絞り、採用しなかった案と不利益も記録します。変更時には過去を消さず新しい記録で置換することで、チームは同じ議論を繰り返さず、前提の変化を根拠に再判断できます。
参考資料
- ADR GitHub Organization
- AWS Prescriptive Guidance: Using architectural decision records
- Microsoft Azure Well-Architected Framework: Architecture decision records
