ADR

(えーでぃーあーる/アーキテクチャ決定記録/Architectural Decision Record/Architecture Decision Record)

文書で確認(海外)
2011年
更新
2026-11-04

一言でいうと

アーキテクチャに関わる重要な判断を1件ずつ、背景・決定・結果とともに記録する短い文書です。Architecture Decision Recordの略で、Architectural Decision Recordとも表記されます。

面接では、記録を書く運用の有無に加え、どの判断を候補者が起案し、チームがどう決定したかを質問します。

提唱者と登場年

2011年11月15日、Michael NygardがCognitectのブログで「Documenting Architecture Decisions」を公開し、ADRの形式を示しました。2011年はこの記事の公開年で、判断を文書に残す取り組みの開始年ではありません。

記事が示した項目は、Title、Context、Decision、Status、Consequencesの5つです。Statusにはproposed、accepted、deprecated、supersededを記載し、文書全体は1〜2ページに収めます。

何を解決するか

開発が長く続くと、ある判断がなぜ下されたのかを追跡しにくくなります。理由を知らない新しい参加者は、その判断をそのまま受け入れるか、影響を理解しないまま覆すかの二択に迫られ、どちらもプロジェクトに害を及ぼしかねません。ADRに理由を残しておくと、前提が変わったときに、その判断が今も妥当かをチームが検討できます。

記録の対象は、すべての判断ではありません。システムの構造、非機能要件、コンポーネント間の依存関係、APIなどのインターフェース、ライブラリやツールを含む構築手法に影響する判断です。

メンバーが入れ替わる組織や、判断に関わらなかった人が後から同じシステムを変更する組織で、この記録は役立つと考えられます。書き方と保存先をチームで統一しておくと、運用しやすくなります。

実際の進み方

判断が必要になると、担当者を決め、チーム共通のテンプレートでADRを作成します。AWSのガイドでは、担当者がProposed(提案中)の状態で提出し、チームでレビューします。会議の冒頭に10〜15分の読む時間を設ける進め方も示されています。

同じガイドでは、修正が必要な場合はProposedのまま修正を続け、却下する場合は理由を記載してRejectedにし、承認する場合は日時、バージョン、関係者を記載してAcceptedにします。

承認後のADRは書き換えません。判断を変更するときは新しいADRを作成し、承認されたら古いADRをSupersededにします。コードレビューでADRに反する変更を発見したレビュアーがADRへのリンクを示して修正を依頼する例も、同じガイドに示されています。

導入でよくある失敗

  • 決定事項だけを書き、背景や採用しなかった選択肢を残さない。その判断が今も妥当かを後から検討できません
  • 承認済みのADRを上書きする。判断がいつ、なぜ変わったのかが履歴に残りません
  • 詳細な設計資料を1件に詰め込む。検討の詳細は別の文書へリンクします
  • 軽微な判断まで記録する。件数が増え、重要な判断を探しにくくなると考えられます

求人票にこの語がある場合に読み取れること

業務内容や歓迎要件に「ADR」がある場合、設計判断の理由を文書に残して参照する運用があるか、その導入を目指している組織だと考えられます。語だけでは運用の実態を判断できないため、自社の求人票では、記録の作成、レビューの進行、最終判断のどこまでを任せるかを書き分けます。

候補者には、自ら起案したADRを1件挙げてもらい、背景、比較した選択肢、受け入れた不利益を質問します。前提が変わってSupersededにした例を話せる場合は、判断の見直しまで関与してきたと考えられます。

隣接手法との違い

用語指すものADRとの違い
デザインドキュメント実装前に設計の目的、選択肢、採用案と理由を書き、レビューで合意を得る文書設計全体を扱う。ADRは判断1件ごとに作成し、承認後は書き換えない
要件定義作るものが満たすべき条件を文書にまとめる工程条件を定める工程。ADRは、その条件を受けて下した判断と理由を記録する
コードレビュー書かれたコードの変更を他者が確認する工程コードの変更が対象。ADRはレビューで判断の基準として参照できる

出典