ADR（Architecture Decision Records）入門

2026年8月8日

🐧 要するにどういう話か

ソフトウェア開発に限らずだが、後で見てわかるように意思決定の記録を残しておきたいが、そこでは何を選んだかよりも、なぜそれを選んだかのほうが重要だったりする。それを捕捉しようというのがADRである。

ADRとは何か

ADR（Architecture Decision Record）は、ソフトウェア開発におけるアーキテクチャ上の重要な決定（Architectural Decision）を記録する仕組みである。

アーキテクチャ上の決定とは、技術スタックの選択、設計パターンの適用、外部サービスとの連携方法など、プロジェクトの構造や非機能要件に影響を与える選択のことである。

目的

ADRの目的は、決定の背景（Why）を残し、チームのナレッジを長期にわたって蓄積することである。

開発プロジェクトでは、多くの決定が逐次行われる。新しいメンバーが参画した際、あるいは既存の決定を見直す際に、過去の決定理由が不明であれば、決定を盲目的に受け入れるか、盲目的に変更するしかなく、どちらもリスクを伴う。ADRは、決定の根拠と影響を文書化することで、この問題を緩和する。

ディレクトリ構成

ADRは通常、プロジェクトリポジトリ内の特定のディレクトリに保存される。

.
└── docs/
    └── arch/
        ├── adr-001.md
        ├── adr-002.md
        └── adr-003.md

ファイル名は adr-NNN.md（NNNは連番）とするのが一般的な慣習である。

Nygard式（オリジナル）

Nygard式は、ADRの元祖となるアプローチである。2011年にMichael Nygardが「Documenting Architecture Decisions」で提唱した。

概要

Nygard式は、アレキサンダーのパターン言語に着想を得ている。各ADRは、力関係（forces）と決定のセットを記録する。力関係とは、決定を左右する要因の集合である。技術的制約、ビジネス要件、チームのスキル、タイムラインなどが該当する。

フォーマットの特徴

Nygard式では、以下のような少ないパートでフォーマットを構成する。

Title: 短い名詞句によるタイトル
Context: 技術的、政治的、社会的、プロジェクト固有の力関係を記述
Decision: 下した決定を記述
Status: 決定の状態（Accepted, Superseded, Deprecatedなど）
Consequences: 決定の結果生じる効果
Acceptance Criteria: 決定が受け入れられるための基準

また、以下の原則を提示する。

決定は短文で記録する
ファイルは doc/arch/adr-NNN.md に保存する
番号は連番で、一度使った番号は再利用しない
決定が覆された場合は、元のファイルを残し、上書きされたことを記録する
MarkdownやTextileなどの軽量マークアップ言語を使用する

例

# ADR-001: データベースにPostgreSQLを採用する

## Context

システムは大量の読み書きを処理する必要があり、データの整合性が要求される。
チームはSQLに慣れている。拡張性が必要で、オープンソースであることが望ましい。

## Decision

PostgreSQLを採用する。

## Status

Accepted

## Consequences

- PostgreSQLのコミュニティが活発であるため、長期のメンテナンスが期待できる
- 初期学習コストが発生する

Nygard式の最大の特徴は、フォーマットを最小限に留め、記録の継続性を優先することである。

MADR（Markdown Architectural Decision Records）

MADRは、ADRをより構造化・実用的にしたフォーマットである。

概要

MADRは、アーキテクチャ上の決定（Architectural Decision）を記録するためのテンプレートを標準化している。

フォーマット

MADRの標準的なテンプレートは、YAML形式のメタデータと、本文のセクションで構成される。

メタデータ

ファイルの先頭にYAMLフロントマターとして、以下のメタデータを記述する。

フィールド	説明
status	決定の状態（proposed, rejected, accepted, deprecated, supersededなど）
date	決定の日付（YYYY-MM-DD形式）
decision-makers	決定に関わった人物
consulted	相談した人物
informed	情報共有した人物

本文

本文は以下のセクションで構成される。

# タイトル

## Context and Problem Statement

問題の文脈と、解決すべき問題を記述する。

## Considered Options

検討した選択肢を列挙する。

## Decision Outcome

選択した決定と、その理由を記述する。

## Consequences

決定の結果生じる効果（Positive / Negative）を記述する。

特徴

MADRの主な特徴は以下の通りである。

構造化: 明確なセクション分けにより、情報の抽出が容易
テンプレート付き: 標準テンプレートを提供し、統一性を確保
ツール連携: markdownlintによるフォーマットチェック
大規模プロジェクト対応: カテゴリ分けによるディレクトリ構成の提案

大規模プロジェクトでの活用法

ADRの数が数百に増えた場合、カテゴリ分けにより整理できる。

.
└── docs/
    └── decisions/
        ├── backend/
        │   ├── adr-001.md
        │   └── adr-002.md
        ├── frontend/
        │   ├── adr-001.md
        │   └── adr-002.md
        └── infrastructure/
            ├── adr-001.md
            └── adr-002.md

例

---
status: accepted
date: 2024-01-15
decision-makers: [Alice, Bob]
consulted: [Charlie]
informed: [Team]
---

# Use Plain JUnit5 for advanced test assertions

## Context and Problem Statement

How to write readable test assertions?
How to write readable test assertions for advanced tests?

## Considered Options

* Plain JUnit5
* Hamcrest
* AssertJ

## Decision Outcome

Chosen option: "Plain JUnit5", because it is a standard framework and the features of the other frameworks do not outweigh the drawback of adding a new dependency.

Y-Statements

Y-Statementsは、決定を極めて簡潔に記録するフォーマットである。Olaf Zimmermannによって提唱された。

概要

Y-Statementsは、IBMのARC-100テンプレートや、より豊かな意思決定モデルの研究を経て、現場の負担を最小限にするために設計された。スポンサーやテックリードが「長文書に時間を割けない」という要望に応えるため、決定をスライド1枚に収めることを目指した。

フォーマット

Y-Statementsの核心は、WHY文法である。以下の6つの要素で構成される。

context 機能的要件（ストーリー、ユースケース）またはアーキテクチャコンポーネント
facing 非機能的要件（ desired quality（望ましい品質）など）
we decided 決定結果（最も重要な部分）
and neglected 選択されなかった代替案（忘れずに記録）
to achieve 利益、要件の完全または部分的な充足
accepting that 欠点や他の影響（short term/long termのコスト・効率を含む）

WHY文法の例は以下の通りである。

In the context of [機能的要件またはアーキテクチャコンポーネント],
facing [非機能的要件],
we decided for [決定結果]
and neglected alternatives [代替案],
to achieve [利益],
accepting that [欠点や他の影響].

特徴

Y-Statementsの主な特徴は以下の通りである。

極めて簡潔: 決定を1文〜短文で記録
WHY文法: context, facing, we decided, alternatives, to achieve, accepting thatの6要素を1文に凝縮
スライド指向: プレゼンテーション資料にそのまま載せられる簡潔さ
現場重視: 記録の負担を最小化し、継続的な運用を可能にする

例

In the context of the Web shop service,
facing the need to keep user session data consistent and current across shop instances,
we decided for the Database Session State pattern
and neglected Client Session State and Server Session State,
to achieve strong consistency across distributed instances,
accepting that it introduces extra database load and operational complexity.

日本語訳:

Webショップサービスの状況において、
ショップインスタンス間でユーザーセッションデータを整合性のある最新の状態に保つ必要性に直面し、
分散インスタンス間で強い整合性を達成するため、
Database Session Stateパターンを選択し、
Client Session StateおよびServer Session Stateを採用せず、
データベース負荷の増加と運用の複雑さを導入することを了承する。

ADR作成のベストプラクティスとアンチパターン

ADRの作成には、良い実践と避けるべきパターンがある。Olaf Zimmermannによる提言を参考にする。

ADRの性質

ADRは以下の性質を持つ。

要約: 必要最小限の情報を凝縮する
採決: 選択したオプションのprosとconsをバランスよく記述し、トレードオフを説明する
意思表明: 決定者を特定し、責任を明確にする
行動計画: 決定は実行され、見直される可能性がある

ベストプラクティス

優先度と重要性で選択する。少なくともアーキテクチャ上重要な要件（architecturally significant requirement）に関する決定を記録する。
高インパクトな決定を遅延させない。データベースやプログラミング言語の変更は、何回もやり直しできるものではない。
メタ品質を優先する。観測性や対応能力など、長期的なビジョンよりも優先すべき指標がある。
実際の要件と経験に基づいて決定する。バイアスに注意し、客観性を保つ。
編集品質に投資する。タイプミスや句読点の問題は、決定の軽視と受け取られる。
段階的に決定する。短期の妥協、中期の解決策、長期のビジョンを別々に決定する。
自信レベルを開示する。迷いがある場合は正直に記述し、変更可能な姿勢を示す。

アンチパターン

以下は避けるべき代表的なアンチパターンである。

Fairy Tale: prosのみを記述し、consを省略する。単なる望み通りの思考。
Sales Pitch: マーケティング的な誇張表現を用いる。根拠のない形容詞・副詞を避ける。
Free Lunch Coupon: 影響を文書化しない。特に長期的な影響を無視する。
Dummy Alternative: 実際には機能しない選択肢を検討したふりをする。
Sprint: 1つのオプションのみを考慮し、短期的な効果のみを議論する。
Tunnel Vision: ローカルな文脈のみを考慮し、運用や保守の視点を欠く。
Maze: ADRの主題と内容が一致せず、無関係な詳細に議論が逸れる。
Blueprint or Policy in Disguise: ジャーナルの文体ではなく、調理書や法律のような文体になる。
Mega-ADR: 複数の多ページADRに詳細情報を詰め込みすぎる。

ADR作成者の誓約（Author Pledge）

ADR作成者は以下の誓約を守ることが推奨される。

決定トピックをアーキテクチャ上の重要性に基づいて優先する
単一のテンプレートを選択し、そのフォーマットに準拠する
ADRのサイズを適切に決定し、決定の質問・基準・オプション・結果・影響を明示する
ドキュメントの品質に投資する
正直かつ率直である。決定の成熟度（自信レベル）を開示する

比較と使い分け

Nygard式、MADR、Y-Statementsの3つを比較する。

項目	Nygard式	MADR	Y-Statements
フォーマット	Title/Context/Decisionなど	YAMLメタデータ + 構造化テンプレート	極めて簡潔なWHY文法
長さ	短文	中程度	1文〜短文
目的	決定の記録	実用的な記録・共有	軽量な記録
学習コスト	低い	中程度	低い
維持コスト	低い	中程度	低い
読みやすさ	標準	高い	高い
大規模化	困難	容易	標準

使い分けのアドバイス

小規模プロジェクト・個人開発: Nygard式またはY-Statementsが適している。フォーマットのオーバーヘッドを最小限にできる。
中規模〜大規模プロジェクト: MADRが適している。構造化により情報の抽出が容易で、カテゴリ分けによる整理も可能。
会議・レビューでの共有: Y-Statementsが適している。スライドや資料にそのまま載せられる簡潔さ。

どのフォーマットを選ぶにせよ、重要なのはフォーマットそのものではなく、決定を記録し続けることである。

📚 参考文献

PENGUINITIS