ADR（Architecture Decision Record）とは｜書き方・Markdownテンプレート・design docとの違い

ADR（Architecture Decision Record／アーキテクチャ決定記録）は、設計上の判断を1件ずつ、背景と理由ごと1つのファイルに残す記録です。コードと構成図には「何を作ったか」が残りますが、「どの案を比べて、何を捨てて、なぜこれにしたか」は残りません。半年後に「この構成は誰が何のために決めたのか」を調べ直す時間を、ADRが省きます。この記事では、Michael Nygardの原典とMADR 4.0.0のテンプレートを一次情報で確かめたうえで、design docとの違い、Markdownでの書き方を整理します。あわせて、実在するOSS4件のADR計272本を数えた結果と、ステータスの揺れを検出するCIスクリプト（手元で実行確認済み）も載せます。

まとめ：ADRの書き方とdesign docとの違いの要点

• 定義：覆すとコストがかかる設計判断を1件1ファイルで残す記録。2011年11月15日にMichael Nygardが公開した形式が原型です。
• design docとの違い：design docは作る前の提案書で、レビューで改訂されます。ADRは決まった一点の記録で、確定後は書き換えません。design docで固まった判断を1件ずつADRへ切り出すのが基本の連携です。
• 書き方：タイトル・ステータス・コンテキスト・決定・結果の5項目を、Markdownでコードと同じリポジトリに置きます。決定は「〜を採用する」と能動態で言い切り、結果には代償も書きます。
• テンプレート：最小はNygard形式。選択肢の比較まで残すならMADR 4.0.0（2024年9月17日公開・2026年10月時点の最新）で、全項目版・最小版と、それぞれの説明文なし版の4種があります。
• 運用：覆った決定は新しいADRで置き換え（Superseded）、古いADRは消しません。実在OSSでは2/4がステータス欄を持たず、持つ側でも表記が18通りに割れていました。表記は最初に固定し、CIで検査するのが確実です。
• 見送り条件：判断を後から読み返す人がいない開発（短期間で捨てるPoCなど）には過剰です。他のメンバーや将来の自分へ判断を引き継ぐ案件で効きます。

ADR（Architecture Decision Record）の定義：1決定1ファイルで「なぜ」を残す記録

ADRの原型は、Michael Nygardが2011年11月15日に公開したブログ記事「Documenting Architecture Decisions」です（旧URLのthinkrelevance.comは現在このページへ301転送されます）。日本語では「アーキテクチャ決定記録」のほか「意思決定ログ」「設計判断の記録」とも呼ばれます。原文は、ADRをプロジェクトのリポジトリに置き、Markdownのような軽量な記法で書き、番号は連番で振って再利用しないと定めています。決定が覆っても古いADRは消さず、supersededと印を付けて残します。1本の長さは「1〜2ページ」で、「未来の開発者との会話のように」完全な文で書く、とされています。

記録する対象は、後から覆すとコストがかかる判断です。MicrosoftのAzure Well-Architected Frameworkは、システムの構造、主要な品質特性に影響するもの、元に戻しにくいものだけを含めるよう書いています。「メッセージ基盤にKafkaでなくSQSを使う」「認証をセッションからJWTに切り替える」は対象で、ボタンの色や変数名の規約は対象外です。層構成やデータの持ち方といった大枠の考え方はシステムアーキテクチャの意味と代表5方式の違いで扱っており、その枠の中で下した個別の選択を1件ずつ残すのがADRです。

この手法は特定ベンダーの流儀ではありません。ThoughtworksのTechnology Radarは「Lightweight Architecture Decision Records」を2016年11月にTrial、2017年11月にAdoptへ上げました。Microsoft、AWS Prescriptive Guidance、Google Cloud Architecture Centerの3社も、それぞれ公式ガイダンスでADRを扱っています。

ADRとdesign docの違い：提案書と決定記録の目的・寿命

ADRとdesign docは、どちらも設計に関わる文書ですが、答える問いが違います。design docは「これから何をどう作るか」、ADRは「なぜ今こうなっているのか」に答えます。混同するとADRが長い設計書になり、誰も書かなくなります。

実務での連携はこう回します。design docのレビューで論点が1つ決着したら、その判断だけを新しいADRとして起票し、design docの該当箇所からADRへリンクします。design docには複数の判断が含まれるので、1本のdesign docから3〜5本のADRが生まれることもあります。design docは出荷後に更新が止まりがちですが、判断の理由はADR側に残ります。現状の構成や仕様は、設計書の側で確かめてください。design doc側の章立てと項目はデザインドック（Design Doc）の書き方の手順と項目テンプレートにまとめています。

議事録は決定の経緯を含んでいても、特定の判断に後からたどり着く索引が無いので、ADRの代わりになりません。設計書は「今どうなっているか」、ADRは「どうしてそうなったか」に答えるもので、片方があってももう片方の問いには答えられません。

ADRの書き方：Nygard形式の5項目と記入例

Nygardの原典が定める項目は5つです。項目を増やすより、この5つを短く埋めることを優先してください。

原典の並びは Title→Context→Decision→Status→Consequences ですが、後述のadr-toolsの雛形はStatusを日付の直後に置いており、こちらの並びが広く使われています。どちらでも構いません。チーム内で1つに揃えることのほうが大事です。次の記入例は、そのまま複製して使える最小テンプレートです。

# 7. メッセージ基盤にAmazon SQSを採用する

Date: 2026-10-15

## Status

Accepted

## Context

注文処理を非同期化したいが、専任の運用担当がいない。
自前のメッセージブローカーを構築・運用する余力はない。
確信度は中程度。ピーク時の流量は未計測で、半年後に見直す前提とする。

## Decision

メッセージ基盤に Amazon SQS を採用する。Kafka の自前運用は採用しない。

## Consequences

- マネージドなので運用の手間が小さい。
- 厳密な順序保証が要る箇所は FIFO キューの設計で別に補う必要がある。
- 流量が想定を超えたら、新しいADRでこの決定を置き換える。

手が止まりやすいのは結果（Consequences）です。ここには、決定で得られるもの・引き換えに諦めたもの・先送りした課題の3種を書きます。「順序保証は別に補う必要がある」のように、次の担当者が踏む問題を先に書いておけば、後の判断がその1行から始められます。記入例のコンテキストに確信度を書いたのは、Microsoftのガイダンスが「確信度の低いまま下した判断は、その低さを記録しておくと後の見直しに役立つ」と勧めているためです。決定文に「Kafkaの自前運用は採用しない」と却下した案を書くと、同じ議論の蒸し返しを防げます。

置き場所は docs/adr/ のような専用ディレクトリにし、ファイル名は4桁ゼロ埋めの連番と英小文字のスラッグ（例 0007-adopt-amazon-sqs.md）にします。日付はファイル名でなく本文に持たせると、連番と時系列を両立できます。日付をファイル名に入れる流儀もあり、後述のShopwareは 2020-06-25-implement-architecture-decision-records.md の形です。

MADR 4.0.0のテンプレート4種とY-statementの選び方

選んだ案だけでなく、比べた案と却下の理由まで構造化して残したいなら、MADR（Markdown Architectural Decision Records）を使います。2026年10月時点の最新は2024年9月17日公開の4.0.0です。リポジトリの開発ブランチには2026年3〜4月に説明文の改訂（決定の範囲を明示する、fitness functionの有無を書く、など）が入っていますが、見出しの構成は4.0.0と同じで、新しいリリースは出ていません。4.0.0のタグには次の4種のテンプレートが入っています。

全項目版の本文は Context and Problem Statement／Decision Drivers／Considered Options／Decision Outcome（その下に Consequences と Confirmation）／Pros and Cons of the Options／More Information です。最小版は Context and Problem Statement／Considered Options／Decision Outcome／Consequences だけになります。front-matterの5キー（status・date・decision-makers・consulted・informed）はテンプレート上で「任意」と明記されています。読み落としやすい点が2つあります。statusの候補は proposed／rejected／accepted／deprecated／superseded by ADR-0123 で、Nygard形式に無い rejected が入っていること。dateは起票日ではなく「決定を最後に更新した日」と定義されていることです。

Confirmationは「決定どおりに実装されたかをどう確かめるか」を書く欄です。テンプレートの説明文は、設計レビューやコードレビュー、ArchUnitのようなライブラリによるテストを例に挙げています。「ドメイン層はインフラ層に依存しない」と決めたなら、それを検査するテストへのリンクを置く、という使い方です。

さらに短くしたいときは、Y-statementという1文形式があります。Uwe ZdunとOlaf Zimmermannらが2013年のIEEE Software論文「Sustainable Architectural Design Decisions」で示した型で、著者らの2018年の論文が出典として引いています。

In the context of 〈ユースケース〉,
facing 〈懸念〉,
we decided for 〈採用した案〉
and neglected 〈却下した案〉,
to achieve 〈得たい品質〉,
accepting 〈受け入れる代償〉.

選ぶ基準は「後から誰が何を確かめたいか」です。決定だけ追えればよいならNygard形式で足ります。「なぜ他の案を落としたか」を監査や引き継ぎで説明する必要があるなら、MADR全項目版に寄せてください。最初はNygard形式で始め、比較が要る案件だけMADRに切り替えて構いません。形式が混ざる場合も、ファイル名の規約とステータスの書き方の2つは全ADRで揃えてください。

ADRのステータスと置き換え（Superseded）の運用手順

Microsoftのガイダンスは、ADRを「append-only log」（追記のみの記録）として扱い、受理済みの記録は編集せず、決定が変わったら元の記録を置き換える新しい記録を書いて両者をリンクするよう求めています。AWSのガイダンスも、受理されたADRはimmutable（不変）になると書いています。誤字の修正を除き、Acceptedの本文は触りません。

AWS Prescriptive Guidanceが示すレビュー手順は、そのまま取り入れやすい形です。起票者（ADR owner）はProposedで出し、レビュー会議の冒頭に10〜15分の黙読時間を取り、各自がコメントと質問を書き込んでから議論します。結論は3つで、受理ならAccepted、手直しが要るならProposedのまま、却下ならRejectedです。却下時には理由を書き添えます。同じ議論が再燃したときに、その理由を示せば済むからです。この流れはPull Requestのレビューと同じ器に載るので、コードレビューの観点と進め方の運用設計をそのまま流用できます。

置き換えの手順は次のとおりです。新しいADRを起票してレビューを通し、受理されたら、古いADRのステータスを「Superseded by ADR-0012」のように置き換え先の番号付きで書き換えます。古いADRで変えてよいのはこのステータス行だけです。決定が不要になっただけで後継が無い場合はDeprecatedにします。

実在OSSのADR272本の実測：ステータス欄・命名・本数

原則どおりに運用されているのかを確かめるため、ADRを公開しているOSS4件のADRディレクトリを、GitHub APIで2026年10月15日に取得して数えました。数えたのは各リポジトリのADRディレクトリ直下のMarkdownで、テンプレート・索引・例示用のファイル（Shopwareのexamples.md）・付録（cosmos-sdkのADR-050の付録2本）は除いています。

わかったことは3つあります。1つ目に、4件中2件はステータス欄を持っていません。Shopwareはfront-matterにtitle・date・area・tagsだけを持ち、本文は Context／Decision／Consequences の3見出しで、ファイル名の日付が2026年のものだけで34本ある、今も活発なディレクトリです。Backstageの索引ページは「置き換えたら古いADRのステータスを変える」と定めていますが、各ADRにステータス欄は無く、置き換えは題名の「[superseded]」と冒頭の注記で示しています（ADR013→ADR014）。状態の表し方は1つに決まっていなくても運用できる、ということです。

2つ目に、ステータス欄があっても表記は揺れます。cosmos-sdkの60本では、「Proposed」「Accepted Partially Implemented」「Proposed – Implemented」「Abandoned」など18通りの書き方がありました。Proposedで始まるものは26本で、うち17本は変更履歴の最初の日付が2019〜2020年です。提案のまま6〜7年経ったのか、実装済みなのに更新されていないのか、ステータスと日付だけでは判別できません。ステータスを「決定の状態」と「実装の状態」の2つの意味で使い始めると、こうなります。

3つ目に、Nygard形式を素直に守っている例もあります。GOV.UKのインフラリポジトリは24本中23本がAccepted、残る1本は「Deprecated (no superseding ADR)」と後継が無いことまで書いています。

ここから導ける判断はこうです。ステータス欄を持つなら、最初のADR（ADR-0001）で使う語を5つ程度に固定し、実装の進み具合は別の欄か課題管理側に持たせてください。語を固定しないなら、Backstageのように置き換えの表示方法だけでも1つに決めます。どちらも決めずに始めると、本数が増えるほど、どれが現在有効な決定かを見分けにくくなります。

ADRのステータス表記をCIで検査するPythonスクリプト

表記の揺れは、人の注意より機械で止めるほうが確実です。次のスクリプトは、ADRディレクトリの連番ファイルを読み、MADRのfront-matterの status またはNygard形式の ## Status の次の行を取り出して、書式を検査します。許可するのは、単独の状態名（proposed・accepted・rejected・deprecated）と、「superseded by [表示名](ファイル.md)」の形だけです。置き換え先はファイルへのMarkdownリンクで書く規約を前提にしており、MADRのテンプレート例にある「superseded by ADR-0123」のような番号だけの参照は不正として報告します。標準ライブラリだけで動きます。

#!/usr/bin/env python3
"""ADRのステータス表記と、ファイルへの置き換え先リンクを検査する（CIで実行）"""
import re
import sys
from pathlib import Path

STATES = "proposed|accepted|rejected|deprecated"
# 単独の状態名か「superseded by [表示名](ファイル.md)」だけを許可する
# （adr-tools が出力する綴り Superceded も通す）
VALID = re.compile(
    rf"^(?:{STATES}|super[sc]eded by \[[^\]]+\]\(([^)]+\.md)\))$", re.I)

def unquote(value):
    value = value.strip()
    if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
        value = value[1:-1].strip()
    return value or None

def read_status(text):
    # MADR形式：YAML front-matter の status
    m = re.search(r"\A---\n(.*?)\n---", text, re.S)
    if m:
        s = re.search(r"^status:[ \t]*(.*)$", m.group(1), re.M)
        if s:
            return unquote(s.group(1))
    # Nygard形式：## Status の次の空でない行
    m = re.search(r"^##[ \t]*Status[ \t]*\n(?:[ \t]*\n)*(.+)$", text, re.M | re.I)
    return unquote(m.group(1)) if m else None

def main(adr_dir):
    root = Path(adr_dir)
    if not root.is_dir():
        print(f"{adr_dir}: ディレクトリがありません")
        return 1
    files = sorted(root.glob("[0-9]*.md"))
    if not files:
        print(f"{adr_dir}: 連番のADRファイルがありません")
        return 1
    errors = 0
    for p in files:
        status = read_status(p.read_text(encoding="utf-8"))
        if status is None:
            print(f"{p.name}: ステータスがありません")
            errors += 1
            continue
        m = VALID.match(status.rstrip("."))
        if not m:
            print(f"{p.name}: 許可されていないステータス '{status}'")
            errors += 1
        elif m.group(1) and not (p.parent / m.group(1)).exists():
            print(f"{p.name}: 置き換え先 {m.group(1)} が存在しません")
            errors += 1
    print(f"{len(files)}件を検査、問題{errors}件")
    return 1 if errors else 0

if __name__ == "__main__":
    sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "docs/adr"))

macOSのPython 3.9.6で動作を確かめました。正常な3本（MADR形式のacceptedと、引用符付きの置き換え先リンク、Nygard形式のAccepted）は「3件を検査、問題0件」で終了コード0です。異常な6本（「accepted nonsense」、空のstatus、status: ""、存在しない 0009-x.md への置き換え、番号だけの参照、「Proposed – Implemented」）はすべて報告され、終了コード1になりました。存在しないディレクトリやADRが1本も無いディレクトリを指定した場合も終了コード1で止まるので、CIのパス指定ミスで検査が素通りすることはありません。次の章で扱うadr-toolsが出力する綴り「Superceded」も通すようにしてあり、adr-toolsで作った8本は問題0件でした。GitHub Actionsなら、ADRディレクトリに変更があったPull Requestで python3 check_adr.py docs/adr を実行するステップを1つ足します。

ADR管理ツールの現状：adr-toolsの実行結果とLog4brainsの更新状況

採番と雛形作りを自動化するツールの代表は、Nat Pryce製のadr-tools（GitHubスター約5,700）です。最新タグは3.0.0（2018年7月25日）、masterへの最後のコミットは2020年3月30日で、Homebrewで入る版も3.0.0です。2026年10月15日にmasterの最新コミットをGNU bash 5.3で動かし、次の3点を確認しました。

• 日本語タイトルはロケール次第で消える：ファイル名のスラッグは tr -Ccs [:alnum:] - で作られます。ロケールがC（LANG未設定のCIコンテナに多い）だと、「メッセージ基盤にAmazon SQSを採用する」は 0002-amazon-sqs.md、「監視基盤を決める」は 0006-.md になりました。ja_JP.UTF-8 では日本語がファイル名に残ります。2017年の利用記事に載っている 0002-adr.md も同じ現象です。
• 置き換えは旧ADRのステータス行を書き換える：adr new -s 2 "…" を実行すると、旧ADRのStatusが「Accepted」から「Superceded by [3. …](0003-….md)」に置き換わり、新ADRには「Supercedes」が入ります。綴りはsupersedeではなく「Superceded」です。grepやCIで検索するなら両方の綴りを拾ってください。
• 雛形の本文は英語の説明文：Context／Decision／Consequencesには英語のプレースホルダーが入り、ADR-0001のリンク先は旧URLのthinkrelevance.comのままです。

ADRのMarkdownから閲覧用の静的サイトを作るLog4brainsは、GitHubのリリースv1.1.0が2024年12月17日で（npmの最新も1.1.0）、developブランチへのコミットもその日が最後です。どちらも数年単位で更新が止まっているので、採用するなら、不具合が出ても自分たちで回避できる範囲で使う前提にしてください。

判断としては、ADRの本数が少ないうちはツールを入れず、テンプレートファイルの複製と前章のCIスクリプトで回してください。採番の手間は1行で済み、外部ツールの更新停止に運用が引きずられません。ツールが活きるのは、連番の一覧から目的のADRを探す手間が目立ってきたときと、開発者以外へ閲覧用サイトとして配るときです。テンプレートの収集では、adr.github.ioのほか、スター約1万7千で2026年10月も更新されている architecture-decision-record/architecture-decision-record（旧 joelparkerhenderson/architecture-decision-record）が多くの書式例をまとめています。

AIコーディング支援とADR：却下した案を再提案させない書き方

エージェント型のAIコーディング支援はリポジトリのテキストを読んで実装方針を組み立てるため、判断がチャットにしか無いと、過去に却下した構成を何度でも提案してきます。ADRがリポジトリ内のMarkdownで残っていれば、それが制約の材料になります。書き方で足すのは2点だけです。決定を「〜を採用し、〜は使わない」と却下側まで書き切ることと、製品名やライブラリ名を正式名で書くことです。あとはリポジトリ直下のAI向け指示ファイルから docs/adr/ を参照させます。AI向けに1本を長くするのは逆効果で、1〜2ページの原則はそのまま守ってください。

ADR導入でよくある失敗と見送ってよい条件

ADRは仕組みが軽い分、つまずく型も決まっています。

• あらゆる決定を記録しようとする：負担で続きません。覆すとコストがかかる判断に絞ります。アーキテクチャ以外の決定まで広げる是非はAny Decision Recordの判断基準と運用設計で扱っています。
• 後からまとめて書く：決定の直後でないと、価値の中心であるコンテキストが痩せます。
• 結果に良い面しか書かない：Nygardの原典は悪い面・中立の面も「すべて」書くよう求めています。代償が無いADRは、後で「想定内だったのか」を判断できません。
• 受理済みのADRを上書きする：判断の変遷が消えます。
• ステータスの語を決めずに始める：前述のcosmos-sdkのように、提案中か実装済みかが読めなくなります。

一方で、判断を後から読み返す人がいない開発、たとえば短期間で捨てるPoCにADRは過剰です。ADRは、判断を共有する相手か、引き継ぐ未来の自分がいて初めて効く仕組みだからです。一人開発でも、数年保守する前提なら書く価値があります。導入するかどうかは人数ではなく、「この判断の理由を、いつか誰かが聞くか」で決めてください。書く文化そのものが無いチームでは、ADRの前にエンジニアがドキュメントを書かない理由と、書く行為を工程に組み込む方法から手を付けるのが先です。

受託開発・保守運用でADRを引き継ぎ資産にする判断

ADRの効果が最も大きいのは、作るチームと運用するチームが別になる案件です。外部に開発を委託すると、納品物は動くコードと設計書で、「なぜその構成にしたか」は委託先の頭の中に残ります。数年後に改修や移行を検討すると、まず現行構成の意図を読み解く調査から始めることになり、その調査が見積りを押し上げます。この状態は属人化の原因とリスクそのものです。

そこで、外部委託する案件では成果物にADRを含めることを契約段階で決めておきます。「アーキテクチャに影響する判断のみ」「1件1〜2ページ」「Markdownでリポジトリに格納」の3条件を書いておけば、対象と分量についての認識違いは防げます。記録漏れは、納品時のレビューでADRの一覧と設計上の主要な判断を突き合わせて確かめます。既存システムを引き取る側では、ADRが無い状態から始まります。Microsoftのガイダンスも、既存システム（brownfield）では分かっている過去の決定から遡ってADRを作るよう勧めています。他社が開発したシステムを保守運用・内製化支援で引き継ぐ場面でも、最初に現行構成の調査結果を後追いのADRとして起こしておくと、以降の改修判断を同じ土台に載せられます。ADR以外の運用ドキュメントの優先順位はシステム運用保守ドキュメントの整備手順が参考になります。

開発と運用の担い手が分かれる案件、外部委託や内製化への移行を含む案件では、ADRを成果物として明示的に定義してください。同じチームが開発から運用まで続けて担当するなら、契約要件にせずチーム内の規約で足ります。

よくある質問

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

design docは実装前に「何をどう作るか」を提案し合意するための文書で、レビューで改訂されます。ADRは決まった判断1件とその理由を残す記録で、確定後は書き換えません。design docのレビューで決着した論点を1件ずつADRへ切り出し、design docからリンクする関係です。

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

必須ではありませんが、Markdownでコードと同じGitリポジトリに置く形が主流です。Nygardの原典もMarkdownのような軽量記法を指定しており、Google Cloudのガイダンスも関連コードの近くにMarkdownで置くことが多いと書いています。差分レビューと履歴がコードと同じ流れに乗るためです。

MADR 4.0は何が変わりましたか？

2024年9月17日公開の4.0.0は、3.0.0（2022年10月）と比べて、front-matterの deciders が decision-makers に改名され、Validation の欄が Confirmation として Decision Outcome の下へ移りました。テンプレートは3.0.0の1種から、全項目版・最小版と、それぞれの説明文なし版の4種に増えています。2026年10月時点でも4.0.0が最新です。

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

Nygardの原典は proposed・accepted・deprecated・superseded の4つ、MADR 4.0.0のテンプレートはこれに rejected を加えた5つを挙げています。実装の進み具合をステータスに混ぜると表記が揺れるので、使う語は最初のADRで固定してください。

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

誤字の修正を除き、受理済みの本文は書き換えません。方針が変わったら新しいADRを起票し、古いADRのステータスだけを「Superseded by ADR-0012」のように置き換え先付きで更新します。判断の変遷そのものが記録として残ります。

関連記事

• デザインドック（Design Doc）とは：書き方の手順と項目テンプレート、AIでの下書きとレビュー
• Any Decision Recordとは｜ADRの範囲をAnyに広げる判断基準とテンプレート・運用設計
• アーキテクチャ図とは？書き方の手順とC4モデル・AWSアイコンの規約、作成ツールの選び方
• ヘキサゴナルアーキテクチャとは？ポートアンドアダプターの仕組みとクリーン・オニオンとの違い
• 属人化とは？原因・リスクと脱属人化を進める仕組み化・標準化の実務