ADR（Architecture Decision Record）がAIエージェントに刺さる理由

この記事でわかること:

• ADRがAIエージェントに刺さる理由
• AIに読まれることを前提としたADRの書き方
• 運用のポイントと2026年の事例

結論: ADRはAIエージェントへの「指示書」になった

ADR（Architecture Decision Record）はもともと人間のための文書でしたが、2026年はAIエージェントへの最強の指示書として再評価されています。「なぜこの設計を選んだか」をAIに伝えることで、改修時の精度が驚くほど上がります。

ADRとは何か

ADRは「アーキテクチャ上の重要な意思決定を記録するドキュメント」です。1決定につき1ファイル、典型的には以下の構造を持ちます。

• タイトル（例: ADR-007 認証にOAuth 2.1を採用
• ステータス（提案中／承認／廃止
• コンテキスト（背景・なぜ決定が必要か
• 決定内容
• 結果（メリット・デメリット・トレードオフ

なぜAIに刺さるのか

AIエージェントは現在のコードは読めますが、「なぜそうなっているか」は読めません。たとえばRedisを使っているコードを見ても、なぜMemcachedではなくRedisなのか、なぜPostgreSQLのキャッシュ機能を使わないのか、までは分かりません。

ADRがあれば、AIは改修時にこれを参照します。「キャッシュをやめてRedisを削除しよう」という提案をする前に、「ADR-012で『セッション管理のために永続性が必要』と決定されているため、Redisは削除できない」と判断できるようになります。

AIに読まれるADRの書き方

1. 検討した選択肢を全部書く

採用した案だけでなく、検討して捨てた案も列挙します。AIは「なぜそれを選ばなかったか」を理解できると、似た提案を再びしません。

2. 数値で根拠を示す

「パフォーマンスが良い」ではなく「レイテンシ 50ms → 12ms」のように数値で書きます。AIは数値を強く重視します。

3. 失効条件を書く

「ユーザー数が100万を超えたら再評価」のような失効条件を書きます。AIは時系列を理解しないため、いつまで有効な決定かを明示しましょう。

4. リンクを張る

関連するPR、計測結果、外部ドキュメントへのリンクをすべて記載します。AIはリンク先まで読みに行きます。

2026年版テンプレート

# ADR-NNN: [決定タイトル]

## ステータス
承認済み（2026-04-15）

## コンテキスト
（3〜5行で背景）

## 検討した選択肢
1. 案A: ...
2. 案B: ...
3. 案C: ...

## 決定
案Aを採用

## 理由
- 数値根拠1: ...
- 数値根拠2: ...

## トレードオフ
- メリット: ...
- デメリット: ...

## 失効条件
- ユーザー数が10万を超えたら再評価
- 関連PR: #1234

運用のポイント

配置場所

リポジトリ直下にdocs/adr/ディレクトリを作り、0001-xxx.mdのように連番でファイルを作ります。AIが探しやすい構造が最重要です。

CLAUDE.mdとの連携

CLAUDE.mdに「重要な設計判断はdocs/adr/を参照すること」と明記します。AIは指示があれば確実に読みに行きます。

更新ルール

ADRは原則として更新しません。状況が変わったら新しいADRを起こし、古いADRのステータスを「廃止（Superseded by ADR-NNN）」に変更します。履歴を残すことが重要です。

2026年の事例

あるBtoB SaaSチームでは、200個のADRを整備した結果、AIエージェントの改修提案で「過去の決定に反する提案」が月平均23件から3件まで減りました。レビュー工数の削減効果は1日あたり1時間以上と試算されています。

まとめ

ADRはAIエージェント時代の最強ドキュメントです。「なぜ」を残すことで、AIは将来の改修で過去の決定を尊重できるようになります。2026年に強いチームは例外なくADRを整備しています。1日10分から始めて、まず10個のADRを書いてみてください。