ADR（アーキテクチャ決定記録）とは｜書き方・テンプレート・design docとの違い

ADR（Architecture Decision Record／アーキテクチャ決定記録）は、設計上の意思決定と「なぜそう決めたか」を1決定1ファイルで残す軽量なドキュメントです。コードやアーキテクチャ図には「何を作ったか」は残りますが、「どの選択肢を比べ、何を捨てて、なぜこれにしたか」は残りません。半年後に「この構成、誰がいつ何のために決めたのか」と調べ直す手間を、ADRがなくします。この記事では、ADRの定義から5項目の書き方、Markdownテンプレート、design docや設計書との違い、運用でのステータス管理までをエンジニア視点で整理します。

まとめ

ADRは、設計判断とその背景・理由を時系列で残す数百文字程度の記録です。要点は次のとおりです。

• 定義：1つの重要な設計判断につき1ファイル。Michael Nygardが2011年に提唱した形式が事実上の標準。
• 書く項目：タイトル／ステータス／コンテキスト（背景）／決定／結果（影響）の5項目。
• 書式：MarkdownでGit管理するのが主流。連番のファイル名（例 0001-…）で並べる。
• design docとの違い：design docは「これから作る設計の提案書」、ADRは「決定した一点とその理由の記録」。粒度と寿命が違う。
• 運用：一度書いたADRは書き換えず、決定が覆ったら新しいADRで上書き（supersede）する。

以下で、それぞれを具体例とともに見ていきます。

ADR（アーキテクチャ決定記録）とは何か

ADRは Architecture Decision Record の略で、日本語ではアーキテクチャ決定記録と訳されます。「意思決定ログ」「設計根拠」と呼ばれることもありますが、指しているものは同じです。記録するのはアプリのコードではなく、アーキテクチャに影響する一回限りの判断です。たとえば「メッセージ基盤にKafkaではなくSQSを採用した」「認証をセッションからJWTに切り替えた」といった、後から覆すのにコストがかかる決定が対象になります。

この形式を広めたのは、ソフトウェアアーキテクトの Michael Nygard が2011年に公開したブログ記事「Documenting Architecture Decisions」です。Martin Fowler も自身のbliki（用語集）でADRを紹介しており、現在は adr.github.io にコミュニティのテンプレート集がまとまっています。1本のADRは1〜2ページ、数百文字で十分というのが本来の思想で、長文の設計書とは性格が異なります。

なぜADRを書くのか｜解決する課題

設計判断の理由は、決めた本人の頭の中か、流れていくチャットやレビューコメントに散らばりがちです。担当者が異動すると背景がまるごと失われ、「なぜこうなっているのか分からないから触れない」コードが残ります。ADRはこの属人化と背景の消失を、決定の瞬間に1ファイル書くだけで防ぎます。

効果がはっきり出るのは次の場面です。新メンバーのオンボーディングでは、ADRを古い順に読むだけで「このシステムが今の形になった理由」を追体験できます。技術的負債の議論でも、「当時はこの制約があってこう決めた」という記録があれば、過去の判断を責めるのではなく前提の変化として扱えます。逆に、ボタンの色のような覆しても痛くない決定まで記録すると形骸化するので、対象は「覆すのにコストがかかる判断」に絞るのが続けるコツです。

ADRの基本フォーマット｜記録する5項目

Nygard形式のADRは、次の5項目だけで構成されます。項目を増やすより、この5つを短く埋めることを優先します。

ステータスは決定の状態遷移を表し、基本はこの4状態です。提案段階が Proposed、合意されたら Accepted、不要になれば Deprecated、別のADRに置き換えられたら Superseded です。とくにコンテキストは、後から読む人が「自分も同じ立場ならこう決めただろう」と納得できるよう、その時点で効いていた制約を正直に書くのが重要です。良し悪しの結論より、判断に至った力学を残すことがADRの価値の中心になります。

ADRのテンプレート｜Markdownでの書き方

Nygard形式の最小テンプレート

ADRはMarkdownで書き、ソースコードと同じGitリポジトリに置くのが主流です。1決定1ファイルとし、ファイル名は連番＋短い説明（例 0007-adopt-sqs.md）にして時系列で並べます。次が、そのまま流用できる最小テンプレートの記入例です。

# ADR-0007 メッセージ基盤にAmazon SQSを採用する

- ステータス: Accepted
- 日付: 2026-06-29

## コンテキスト
注文処理を非同期化したいが、専任の運用チームがいない。
自前のメッセージブローカーを構築・運用する余力はない。

## 決定
メッセージ基盤に Amazon SQS を採用する。

## 結果
- マネージドなので運用の手間が小さい。
- 厳密な順序保証が要る箇所はFIFOキューやリトライ設計で補う。
- 将来スループットが問題化したら、別のADRで採用を見直す。

項目名は日本語でも英語でもよく、チーム内で1つに統一できれば十分です。書き方のコツは、決定を「〜を採用する」と能動態で言い切ること、結果に良い面だけでなく代償と残課題も書くことです。代償が書かれていないADRは、後で「これは想定済みだったのか」を判断できません。

MADRなどテンプレートの選び方

Nygard形式が最小限なのに対し、選択肢ごとの比較や却下理由まで構造化したいときは MADR（Markdown Architectural Decision Records、2017年〜）が向きます。MADRには全項目入りの adr-template.md と必須項目だけの最小版があり、「検討した選択肢」「決定の根拠」などのセクションが用意されています。まず最小テンプレートで始め、比較の記録が必要になったらMADRに寄せる、という進め方が現実的です。MADRの詳細とテンプレートは MADR公式サイト から確認できます。

ADRと設計ドキュメント（design doc）・議事録との違い

「ADRとdesign docは何が違うのか」はよく検索される疑問です。どちらも設計に関わる文書ですが、目的と寿命が異なります。混同すると、ADRが長大な設計書になって続かなくなります。

使い分けの軸はシンプルです。design docは「どう作るかをこれから決めるための提案」、ADRは「決まった理由を後から追えるようにする記録」です。design docの中で重要な判断が固まったら、その一点だけをADRに切り出して残す、という連携がきれいに回ります。議事録は決定の経緯を含みますが、検索性がなく後から特定の判断にたどり着けないため、ADRの代わりにはなりません。

ADRの運用とライフサイクル

ADRの運用で最も大事な原則は、一度Acceptedにしたファイルは書き換えないことです。決定が覆ったら古いADRのステータスを Superseded に変え、置き換え先のADR番号を一行添えて、新しいADRを別ファイルで起こします。こうすることで「いつ・なぜ方針が変わったか」の履歴が連番のまま残ります。過去のADRを上書き修正すると、まさにADRが残そうとしている判断の変遷が消えてしまいます。

管理はリポジトリ内の専用ディレクトリ（例 docs/adr/）にMarkdownを並べるだけで始められます。本数が増えてきたら、連番とタイトルで一覧できるインデックスを用意すると検索性が保てます。作成・採番・ステータス更新を自動化したい場合は、Nat Pryce 製のCLI adr-tools などのツールがあり、adr new のようなコマンドで雛形を生成できます。ただしツールは必須ではなく、Markdownと連番の規約さえ決めれば手作業でも十分回ります。

ADR導入でよくある失敗

ADRは仕組みが軽い分、運用でつまずく型も決まっています。導入前に避けたい失敗を挙げます。

• 全決定を記録しようとする：些末な決定まで対象にすると負担で続かない。覆すのにコストがかかる判断だけに絞る。
• 後からまとめて書く：決定の直後でないと背景（コンテキスト）が薄くなり、価値の中心が抜ける。判断したその場で書く。
• 結果に良い面しか書かない：代償と残課題が無いと、後で「想定内だったのか」を判断できない。
• 古いADRを上書きする：履歴が消える。覆った決定はSupersededにして新規ADRで置き換える。

逆に、一人開発や使い捨てのPoCではADRは過剰です。判断を共有する相手や引き継ぐ未来の自分がいて初めて効果が出る仕組みなので、チーム規模や寿命に見合わないなら無理に導入しなくてかまいません。

ADRに関するよくある質問

ADRとdesign docの違いは何ですか？

design docは実装前に「どう作るか」を提案・合意するための長めの文書、ADRは決まった判断とその理由を後から追えるよう1決定1ファイルで残す短い記録です。design docで固まった重要な判断をADRに切り出す、という関係になります。

ADRはMarkdownで書くべきですか？

必須ではありませんが、Markdownでソースコードと同じGitリポジトリに置く形が主流です。差分レビューや履歴管理がコードと同じ流れに乗り、Pull Requestで決定を議論できるためです。Markdown向けにはMADRというテンプレートも用意されています。

ADRのステータスにはどんな種類がありますか？

提案中の Proposed、合意された Accepted、不要になった Deprecated、別のADRに置き換えられた Superseded が基本です。チームによって名称を足すこともありますが、まずはこの4つで運用できます。

一度書いたADRは修正してよいですか？

誤字修正を除き、決定内容は書き換えません。方針が変わったら古いADRをSupersededにして、新しいADRを別ファイルで作成します。書き換えずに積み上げることで、判断の変遷そのものが記録として残ります。

ADRはどんなツールで管理しますか？

リポジトリ内のディレクトリにMarkdownを連番で置くだけで運用できます。採番や雛形生成を自動化したい場合は adr-tools のようなCLIもありますが、ツールよりも「1決定1ファイル・連番・上書きしない」という規約のほうが重要です。

関連記事

• アーキテクチャ図に「正解」がない理由と背景
• ヘキサゴナルアーキテクチャとは何か？その基本概念と特徴を詳しく解説
• システム設計を効率的に学ぶためのオープンソース「system-design-primer」