Architecture Decision Records (ADR): 完全ガイド - Archyl Blog

Architecture Decision Recordsは、技術的な意思決定の「なぜ」を記録するものです。この完全ガイドでは、ADRのフォーマット、テンプレート、ベストプラクティス、ツール、そしてADRをチームのワークフローに統合する方法を解説し、意思決定の経緯が失われることを防ぎます。

Architecture Decision Records (ADR): 完全ガイド

あらゆるソフトウェアシステムは、数百もの意思決定によって形作られています。PostgreSQLかMongoDBか。RESTかGraphQLか。モノリスかマイクロサービスか。イベント駆動かリクエスト・レスポンスか。それぞれの選択が将来の選択肢を制約し、それらが一体となってアーキテクチャを定義します。

問題は、意思決定が見えないことです。コードは「何が」構築されたかを示しますが、「なぜ」そのように構築されたかは示しません。PostgreSQLを選択してから6ヶ月後、チームがDynamoDBを検討したかどうか、パフォーマンス要件がどうだったか、なぜ結果整合性が受け入れられなかったかを誰も覚えていません。意思決定はコードに組み込まれていますが、その理由は失われています。

Architecture Decision Records（ADR）は、各重要な意思決定を短い構造化された文書として記録することでこの問題を解決します。ADRはソフトウェアエンジニアリングにおいて最もレバレッジの高いドキュメンテーション手法の一つです。導入が簡単で、維持コストが低く、必要な時に非常に価値があります。

このガイドでは、基本から高度な実践まで、すべてをカバーします。ADRとは何か、書き方、すぐに採用できるテンプレート、よくある落とし穴、そしてモダンなツールを使ってワークフローにADRを統合する方法を解説します。

Architecture Decision Recordとは何か？

Architecture Decision Recordとは、単一のアーキテクチャ上の意思決定を記録する短い文書です。ここで重要なのは「単一」と「短い」です。

  • 単一: 1つのADRに1つの意思決定。「注文サービスにPostgreSQLを使用する」は1つのADRです。「データベース戦略全体を設定する」は設計文書であり、ADRではありません。
  • 短い: ADRは1ページに収まるべきです。それより長い場合、複数の意思決定を文書化しているか、実装の詳細を含めすぎている可能性があります。

この概念はMichael Nygardが2011年のブログ記事で広めました。それ以来、ADRはスタートアップから政府機関まで幅広い組織で採用されています。英国政府デジタルサービス、Spotify、そして無数のエンジニアリングチームがADRを標準的な手法として使用しています。

ADRが記録するもの

すべてのADRは4つの基本的な質問に答えます。

  1. コンテキストは何だったか？ どのような状況や問題がこの意思決定を促したのか？
  2. 何を決定したか？ 具体的にどのようなアーキテクチャ上の選択をしたのか？
  3. どのような代替案を検討したか？ 他にどのような選択肢があったのか？
  4. 結果はどうなるか？ この意思決定に伴うトレードオフ、リスク、影響は何か？

これだけです。4つの質問。よく書かれたADRは、1ページ以内でこれらすべてに答えることができます。

ADRが「ではない」もの

  • 設計文書ではない。 ADRは何かがどのように実装されるかを記述しません。「なぜ」特定のアプローチが選ばれたかを記述します。
  • RFCではない。 RFC（Request for Comments）は議論のための提案です。ADRは「結論が出た」意思決定を文書化します（ただし、ADRは提案として始まり、承認に移行することもあります）。
  • 会議メモではない。 ADRは結果を記録します。そこに至る議論ではありません。
  • 包括的なドキュメンテーションではない。 ADRはアーキテクチャ図、API仕様、Runbookを補完するものです。それらに取って代わるものではありません。

標準ADRテンプレート

複数のADRテンプレートが存在しますが、ほとんどは同じコア構造のバリエーションです。以下は、完全性と簡潔さのバランスが取れた実用的なテンプレートです。

# ADR-NNNN: [意思決定を説明する短いタイトル]

## Status

[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]

## Date

[YYYY-MM-DD]

## Context

[状況を説明する。どのような問題を解決しようとしているか？どのような
制約があるか？どのような要因が作用しているか？具体的に記述する --
関連する場合は数値、締切、チームの能力、技術的要件を含める。]

## Decision

[意思決定を明確かつ簡潔に述べる。能動態を使用：
「Xを使用する」であり、「Xを検討すべきである」ではない。]

## Alternatives Considered

### [代替案1]
- 利点: ...
- 欠点: ...
- 却下理由: ...

### [代替案2]
- 利点: ...
- 欠点: ...
- 却下理由: ...

## Consequences

### ポジティブ
- [何がより簡単または良くなるか]

### ネガティブ
- [何がより困難または悪くなるか]

### リスク
- [何がうまくいかない可能性があるか]

## Related Decisions

- [関連するADRへのリンク]

各セクションの詳細

Status は意思決定のライフサイクルを追跡します。典型的なフローはProposed -> Acceptedです。状況が変わった場合、ADRはDeprecatedまたはより新しいADRにSupersededとなります。重要なのは、ADRを決して削除しないことです。却下された意思決定であっても、将来のチームが既に評価済みの選択肢を再検討するのを防ぐ価値があります。

Date は意思決定が行われた時点を記録します。これにより時間的なコンテキストが得られます。「2024年にスケールがXだった時にこの技術を選んだ。現在スケールが10倍になったので、見直すべきだ。」

Context は最も重要なセクションです。よく書かれたContextセクションは、状況が変わった後でも、「なぜ」この意思決定が当時は妥当だったかを将来の読者が理解するのに十分な情報を提供します。具体的な数値（「1日あたり5万件の注文を処理している」）、制約（「PCI-DSSに準拠する必要がある」）、チーム要因（「3人のエンジニアがPostgreSQLの経験があり、MongoDBの経験者はいない」）を含めてください。

Decision は曖昧さがあってはなりません。「注文サービスの主要データストアとしてPostgreSQL 16を使用する」は良い例です。「リレーショナルデータベースを検討すべきかもしれない」はADRではなく、単なる提案です。

Alternatives Considered は長期的に最も時間を節約するセクションです。新しいエンジニアが「なぜMongoDBを使わなかったのか？」と聞いた時、答えがここにあります。チームが1年後に意思決定を見直す時、何が評価され、なぜ却下されたかを確認できます。このセクションがないと、チームは同じ議論を際限なく繰り返すことになります。

Consequences は知的誠実さについてです。すべての意思決定にはトレードオフがあります。デメリットを認めることは信頼を構築し、将来のチームが状況の変化により意思決定を見直す必要があるかもしれない時期を理解する助けになります。

完全なADRの例

以下は、テンプレートの実践を示す現実的なADRです。

# ADR-0023: サービス間通信にApache Kafkaを使用する

## Status

Accepted

## Date

2025-11-15

## Context

当プラットフォームは過去1年で3つのマイクロサービスから12に成長した。
サービスは現在HTTP REST呼び出しで同期的に通信している。これにより
いくつかの問題が生じている：

- カスケード障害：Inventoryサービスがダウンすると、在庫チェックは
  結果整合性で十分であるにもかかわらず、Orderサービスが注文を
  処理できなくなる。
- 密結合：サービスは互いのAPIコントラクトとエンドポイントを
  知る必要がある。
- パフォーマンスのボトルネック：一部の操作では4〜5回の同期呼び出しの
  連鎖が発生し、レイテンシーが増加する。

1日あたり約10万件のイベントを処理している。12ヶ月以内に50万件に
成長する見込みである。チームには8人のバックエンドエンジニアがおり、
そのうち2人はKafkaの使用経験がある。

## Decision

サービス間の非同期通信の主要メカニズムとしてApache Kafkaを採用する。
呼び出し元が即座の結果を必要とするリクエスト/レスポンスパターン
（例：認証チェック）では、同期HTTPを引き続き使用する。

運用オーバーヘッドを最小化するために、マネージドKafkaプロバイダー
としてConfluent Cloudを使用する。

## Alternatives Considered

### RabbitMQ
- 利点：運用がシンプル、学習コストが低い、複数のメッセージング
  パターンをサポート（pub/sub、ポイントツーポイント、ルーティング）。
- 欠点：採用予定のイベントソーシングパターンにはあまり適していない。
  リプレイ/巻き戻し機能が弱い。イベント駆動アーキテクチャでは
  コミュニティの勢いがKafkaに移行している。
- 却下理由：監査とデバッグのためにイベントリプレイが必要になると
  予測している。Kafkaのログベースのアーキテクチャがより適している。

### AWS SQS + SNS
- 利点：フルマネージド、インフラの保守が不要、AWSとの緊密な統合。
- 欠点：AWSへのベンダーロックイン。メッセージの順序保証が限定的。
  組み込みのストリーム処理がない（KinesisまたはLambdaが必要）。
  予測されるボリュームではメッセージ単価が高い。
- 却下理由：AWSロックインの深化を避けたい。金融イベントには
  順序付きメッセージ配信が必要。

### 同期HTTPを維持する（サーキットブレーカー付き）
- 利点：新しいインフラ不要。チームは既に精通している。サーキット
  ブレーカーがカスケード障害に対処する。
- 欠点：密結合の問題を解決しない。呼び出しチェーン全体でレイテンシーが
  依然として蓄積する。サーキットブレーカーは根本的な結合問題に対する
  場当たり的な対応であり、解決策ではない。
- 却下理由：症状に対処するが、根本原因には対処していない。

## Consequences

### ポジティブ
- サービスが疎結合になる：プロデューサーはコンシューマーを知る必要がない。
- 非同期ワークフローでカスケード障害が排除される。
- イベントリプレイにより強力なデバッグと監査機能が実現する。
- 将来のサービスにおけるイベントソーシングパターンの基盤となる。

### ネガティブ
- 運用の複雑さが増加する（Kafkaクラスター、スキーマレジストリ、
  コンシューマーグループの管理）。Confluent Cloudの使用で軽減。
- チームにKafkaの概念とパターンに関するトレーニングが必要。
- 非同期フローでは結果整合性が強い一貫性に取って代わる。
  一部のワークフローの再設計が必要。
- 分散非同期フローのデバッグは同期HTTP呼び出しのトレースより困難。
  分散トレーシングが必要（ADR-0024を参照）。

### リスク
- メッセージ量がConfluent Cloudの料金ティアを超えた場合、
  コストが大幅に増加する可能性がある。モニタリングとアラートを設定する。
- サービス間のスキーマの進化には規律が必要。スキーマレジストリと
  Avroの採用を計画する。

## Related Decisions

- ADR-0024: 分散トレーシングにOpenTelemetryを採用する
- ADR-0018: サービス通信コントラクト（このADRにより置き換え）

このADRは約400語です。書くのに20分ほどかかりました。今後数年間で何時間もの会議を節約することになるでしょう。

ADRを書くタイミング

すべての技術的な選択にADRが必要なわけではありません。2つのJSONライブラリのどちらかを選ぶのにADRは不要です。しかし、一部の意思決定には絶対に必要です。

ADRを書くべき場合：

  • 意思決定がシステムの構造に影響する場合。 サービス間の通信方法、データの保存場所、コンポーネントの編成方法を変更するあらゆるもの。
  • 意思決定を元に戻すコストが高い場合。 データベース、メッセージングシステム、デプロイメントプラットフォームの選択。この意思決定を取り消すのに1スプリント以上かかる場合、なぜその決定をしたかを記録する。
  • 複数の実行可能な選択肢がある場合。 選択が明らかであればADRは不要。3つの選択肢の間で議論した場合は、その理由を記録する。
  • 意思決定がチームの境界を越える場合。 他のチームに影響するアーキテクチャ上の選択は、彼らがその根拠を理解できるよう文書化すべき。
  • 将来の自分がその選択に疑問を持つ可能性がある場合。 誰か（将来の自分を含む）が「なぜこうしたのか？」と聞く可能性が少しでもあるなら、今のうちに記録する。

ADRを省略してよい場合：

  • 選択が確立されたチーム標準に従っている場合（例：「バックエンドサービスには常にGoを使用する」は各サービスごとに新しいADRを必要としない）
  • 意思決定が簡単に元に戻せる場合（変数名の変更、コードフォーマッターの選択）
  • 意思決定が純粋に外観的な場合（コードスタイル、命名規則 -- これらはスタイルガイドに属する）

ADRのライフサイクルとガバナンス

ライフサイクル

ADRには自然なライフサイクルがあります。

  1. Draft/Proposed: 誰かが意思決定の必要性を特定し、ADRのドラフトを作成する。チームが議論する。
  2. Accepted: チームが意思決定に合意する。ADRのステータスがAcceptedに変わる。
  3. Active: 意思決定が有効である。ADRはリファレンスドキュメンテーションとして機能する。
  4. Superseded: 新しい意思決定がこれを置き換える。古いADRに「Superseded by ADR-XXXX」のステータスが付く。新しいADRは古いものを参照する。
  5. Deprecated: 意思決定がもはや関連性がない（おそらく適用されていたシステムが廃止された）。

重要：ADRは決して削除しないでください。廃止またはSupersededされたものでも価値があります。それらはアーキテクチャの進化のタイムラインを形成します。

ナンバリング

連番を使用します：ADR-0001、ADR-0002など。番号は時系列の順序を提供し、会話の中でADRを簡単に参照できるようにします。「ADR-42で決定された通り。」

日付ベースのナンバリング（ADR-2026-03-27-kafka）を使用するチームもありますが、連番の方がシンプルでより広く使用されています。

レビューの頻度

四半期ごとにADRをレビューするリマインダーを設定してください。

  • 承認済みの意思決定で、もはや有効でないものはないか？
  • 前提を無効にするような制約の変化はないか？
  • チームが非公式に行った意思決定で、記録すべきものはないか？

このレビューにより、ADRの劣化を防ぎ、コレクションを最新の状態に保ちます。

ADRの保存場所

推奨順に最も一般的なアプローチを紹介します。

コードリポジトリ内

リポジトリ内の docs/adr/ または docs/decisions/ にADRを保存します。これは最も人気のあるアプローチであり、正当な理由があります。

  • ADRは記述するコードと一緒にバージョン管理される
  • プルリクエストやコードレビューに表示される
  • 誰も訪れないWikiで孤立することがない
  • grep や検索で発見可能

慣例：ADRごとに1つのMarkdownファイル。番号とスラグで命名します。

docs/adr/
  0001-use-postgresql-for-orders.md
  0002-adopt-event-driven-architecture.md
  0003-monorepo-for-frontend.md

専用のアーキテクチャツール内

Archylのようなツールは、追加機能を備えたADR管理を組み込みで提供します。

  • ADRをC4モデル要素（コンテナ、コンポーネント、リレーションシップ）に直接リンク
  • すべてのプロジェクトにわたるADRの検索とフィルタリング
  • ADRのステータスとライフサイクルの追跡
  • ADRを意思決定を強制する適合性ルールに接続

アーキテクチャツールの主な利点はコンテキストです。開発者がC4図のPostgreSQLコンテナを見る時、なぜPostgreSQLが選ばれたかを説明するADRにクリックしてアクセスできます。意思決定とアーキテクチャがサイロ化されずに接続されています。

Wiki内（推奨しない）

Wiki（Confluence、Notionなど）はADRが忘れ去られる場所です。コードから切り離され、発見しにくく、めったにメンテナンスされません。Wikiを使わざるを得ない場合は、少なくともコードリポジトリからADRへのクロスリファレンスを作成してください。

ADRをワークフローに統合する

プルリクエストの一部にする

重要なアーキテクチャの変更には、プルリクエストの一部としてADRを要求してください。PRテンプレートにセクションを追加します。

## Architecture Impact

- [ ] アーキテクチャの変更なし
- [ ] ADR作成/更新済み: [リンク]

これによりADR作成が標準化され、コンテキストが薄れる数週間後ではなく、意思決定が行われた時に確実に文書化されます。

アーキテクチャレビューでADRを使用する

アーキテクチャレビューや設計議論の中で、既存のADRを参照してください。「これを再設計する前に、ADR-15がなぜこのアプローチを選んだかについて何と言っているか確認しよう。」これによりADRの可視性が高まり、意思決定を文書化する習慣が強化されます。

ADRをアーキテクチャ図に接続する

ここがADRが真に強力になるポイントです。ADRがC4モデルの特定の要素にリンクされると、ナビゲート可能な知識グラフが作成されます。

  • コンテナ図のKafkaコンテナをクリック -> なぜKafkaが選ばれたかを説明するADR-0023を表示
  • PostgreSQLデータベースをクリック -> データベース選定を説明するADR-0001を表示
  • API Gatewayをクリック -> カスタムルーティングよりKongが選ばれた理由を説明するADR-0012を表示

Archylでは、ADRをあらゆるC4要素（システム、コンテナ、コンポーネント、リレーションシップ）にリンクできます。この接続により、アーキテクチャ上の意思決定は浮遊するドキュメントではなく、影響を与えるアーキテクチャの特定の部分に固定されます。

自動化できるものは自動化する

いくつかのツールがADR管理の摩擦を軽減します。

  • adr-tools（Nat Pryce作）：リポジトリ内でADRを作成・管理するコマンドラインツール。adr new "Use Kafka for messaging" を実行するとテンプレートから新しいADRが生成されます。
  • Log4brains：ADRのMarkdownファイルから検索可能で閲覧可能なWebサイトを生成します。
  • Archyl：C4要素へのリンク、ステータス追跡、プロジェクト横断検索機能を持つADR管理を提供します。

ADRの高度な実践

Lightweight ADR（LADR）

一部のチームは標準テンプレートでさえ重すぎると感じます。Lightweight ADRは3つの文で構成されます。

[状況]というコンテキストにおいて、
[目標]を達成するために[意思決定]を決定し、
[トレードオフ]を受け入れる。

例：

サービスのダウンタイムを許容するサービス間通信が必要という
コンテキストにおいて、サービスの疎結合とイベントリプレイ機能を
達成するためにConfluent Cloud経由でApache Kafkaを使用することを
決定し、運用の複雑さの増加と結果整合性を受け入れる。

このフォーマットは、文書化するほど重要だが完全なADRを正当化するほどではない意思決定に適しています。

Decision Log

Decision Logは、すべてのADRを時系列順に1行の要約とともに一覧化する単一の文書です。インデックスとして機能します。

# Date Decision Status
23 2025-11-15 サービス間通信にKafkaを使用する Accepted
24 2025-11-20 分散トレーシングにOpenTelemetryを採用する Accepted
25 2025-12-01 内部APIをRESTからgRPCに移行する Proposed

これにより、個別のADRファイルを開かずにすべての意思決定の概要を把握できます。

非技術的な意思決定のためのADR

ADRは技術の選択に限定されません。チームは以下のような用途で使用しています。

  • プロセスの意思決定：「セキュリティクリティカルなコードにはペアプログラミングを行う」
  • 組織の意思決定：「プラットフォームチームがすべてのインフラコンテナを所有する」
  • ベンダーの意思決定：「社内構築ではなく、モニタリングにDatadogを使用する」

意思決定が重要であり元に戻すのにコストがかかるものであれば、厳密に「アーキテクチャ」に関するものかどうかに関わらず、ADRが適切です。

よくある落とし穴

事後にADRを書く

ADRを書く最適なタイミングは意思決定プロセスの最中です。数週間後に書くと、ニュアンス、検討した代替案、存在していた制約を忘れてしまいます。ADRの作成を意思決定プロセスの一部とし、後付けにしないでください。

長くしすぎる

ADRが1ページを超える場合、複数の意思決定を文書化している（分割する）か、実装の詳細を含めている（設計ドキュメントに保存する）可能性があります。簡潔さの規律は明確さを強制します。

却下された代替案を記録しない

「Alternatives Considered」セクションは、長期的にADRの中で最も価値のある部分です。これがないと、将来のエンジニアは同じ代替案を提案し、それらが既に評価され却下されたことに気づきません。選ばなかったものとその理由を常に説明してください。

実践を中断する

1つや2つのADRではあまり価値がありません。2年間で蓄積された50のADRは、かけがえのない知識ベースになります。忙しい時にADRの作成をやめたくなる誘惑は強いものです。抵抗してください。ADRを書くのに費やす15分は、後で何時間もの会議を節約します。

ステータスをレビュー・更新しない

半数の意思決定が古くなっているADRコレクションは誤解を招きます。四半期ごとのレビューを予定してください。Supersededされた意思決定にはマークを付けてください。コレクションの信頼性を保ちましょう。

AI時代にADRがより重要になる理由

AIエージェントがソフトウェア開発のアクティブな参加者になるにつれ、ADRは新たな重要性を帯びてきます。コードを書くAIエージェントはADRを読んで以下を理解できます。

  • なぜ特定の技術が選ばれたか（そして引き続き使用されるべきか）
  • どの代替案が却下されたか（そして再提案されるべきではないか）
  • どのような制約が存在するか（コンプライアンス要件、パフォーマンスしきい値）
  • どのようなトレードオフが受け入れられたか（結果整合性、ベンダー依存）

ArchylのMCPサーバーを通じて、Claude CodeのようなAIエージェントはアーキテクチャの提案を行う前にADRにアクセスできます。既にPostgreSQLが選ばれた理由が文書化されているサービスに対してMongoDBを提案するのではなく、エージェントは既存の意思決定を尊重します。あるいは、意思決定を見直すべきだと考える場合は明示的にフラグを立てます。

これにより、ADRは人間のためのドキュメンテーションだけでなく、AIのためのガードレールにもなります。

今日から始める

チームがまだADRを使用していない場合、以下の3つのステップから始めてください。

  1. 最近の意思決定を1つ選ぶ。 チームが先月議論したアーキテクチャ上の選択を思い出してください。上記のテンプレートを使用してADRを書いてください。15〜20分で済むはずです。

  2. リポジトリに保存する。 docs/adr/ ディレクトリを作成し、ファイルを追加してください。次のプルリクエストに含めて、チームに見てもらいましょう。

  3. 習慣にする。 PRテンプレートに「Architecture Impact」チェックボックスを追加してください。次のアーキテクチャミーティングでADRについて議論してください。チームが価値を感じ始めると、実践に勢いがつきます。

次に誰かが「なぜそうしたのか？」と聞いた時 -- そして必ずそうなりますが -- あなたはその答えを持っています。

アーキテクチャドキュメンテーションについてさらに探る: C4モデルとは？ | ADRベストプラクティス | AI搭載アーキテクチャ発見。または、C4モデルに直接リンクされたADR管理のためにArchylを無料でお試しください。