ADR（Architecture Decision Records）をAIと運用する：設計判断を忘れない仕組み

「なぜこの設計にしたのか」——3ヶ月前の自分に聞くことはできない。AIに聞いても「そのセッションの記録は持っていません」と返される。

ADR（Architecture Decision Records、アーキテクチャ決定記録）は、設計上の重要な判断を「コンテキスト → 決定 → 理由 → 影響」のフォーマットで記録する手法です。本記事では、ADRをClaude CodeのCLAUDE.mdと組み合わせて「AIが過去の設計判断を参照できる仕組み」を構築した実践を記録します。

問題：AIが却下済みの設計を再提案する

実際に起きたこと

1
セッション1（2025年9月）:
2
  人間: 「データ分析を高速化したい」
3
  AI:   「各処理ごとに個別に分析する方式を提案します」
4
  人間: 「それは重複計算が多い。統合分析方式にしよう」
5
  → 統合分析アーキテクチャを採用
6

7
セッション2（2026年1月）:
8
  人間: 「新しい処理パターンを追加したい」
9
  AI:   「新しい処理パターン用に個別の分析プログラムを作成します」
10
  人間: 「待って、それは4ヶ月前に却下した設計だ」

AIはセッション間で文脈を共有しません。4ヶ月前に「この方式はダメ」と判断した理由を知らないのです。

ADRのフォーマット

DECISIONS.mdに以下のフォーマットで記録します。

1
## ADR-001: 統合分析アーキテクチャの採用
2

3
### 状態
4
採用（Accepted）
5

6
### 日付
7
2025-09-18
8

9
### コンテキスト
10
各処理タイプが独立して分析を実行し、以下の重複が発生:
11
- 中間集計・日次集計を3回分析（バッチ、リアルタイム、ストリーミングで重複）
12
- 処理時間: 18-19時間
13

14
### 決定内容
15
全集計データを1回だけ分析し、結果を各処理タイプで再利用する。
14 collapsed lines
16

17
### 理由
18
1. パフォーマンス向上: 重複計算排除で80%削減（18h→3-4h）
19
2. 保守性向上: 分析ロジックの一元管理
20
3. 拡張性: 新しい処理タイプ追加が容易
21

22
### 影響
23
- ポジティブ: 処理時間80%削減、バグ修正が1箇所で完結
24
- ネガティブ: メモリ使用量の一時的増加
25

26
### 注意事項
27
⚠️ 今後の修正で絶対に守るべきルール:
28
1. unified_processor.py内で同じデータセットを複数回分析してはいけない
29
2. 条件判定は*OutputFileGeneratorに委譲し、processor側で実装しない

ADRが効いた3つの場面

場面1：個別分析の再提案を却下

AIが新パターン用の個別分析プログラムを提案したとき、DECISIONS.mdを参照して即座に「ADR-001で却下済み」と判断できました。

1
人間: @DECISIONS.md を参照してください。この設計はADR-001で却下されています。
2
AI:   確認しました。統合分析アーキテクチャに従い、
3
      unified_processor.pyに新しい処理ロジックを追加する方式で実装します。

場面2：デッドコードの混入防止

ADR-002で「使用停止」と記録されたモジュールを、AIが別の施策でインポートしようとしました。

1
### ADR-002の注意事項
2
legacyOutputConditions.pyの扱い:
3
- 現在は使用されていないが、ファイルは残存
4
- 新規コードで絶対にインポートしない

場面3：条件判定の実装場所の統一

「トリガー条件をunified_processor.pyに書くべきか、OutputFileGeneratorに書くべきか」の判断で、ADR-001の注意事項が決め手になりました。

CLAUDE.mdとの連携

参照の仕組み

CLAUDE.mdに以下を記載します。

1
## Key References
2
| Document | Description |
3
|----------|-------------|
4
| DECISIONS.md | アーキテクチャ決定記録（ADR形式） |
5

6
## Critical Rules
7
- 設計変更前: DECISIONS.md と Git 履歴を確認する

AIはCLAUDE.mdを毎回読み込むため、「設計変更前にDECISIONS.mdを確認する」というルールが自動的に適用されます。

ADRの粒度

記録すべき判断と記録不要な判断の基準は以下のとおりです。

1
記録する:
2
- アーキテクチャの変更（モジュール構成・データフローの変更）
3
- 技術選定（ライブラリ・フレームワーク・外部サービスの選択）
4
- 設計パターンの採用/却下
5
- 「やらない」と決めたこと（却下した設計案）
6

7
記録しない:
8
- 変数名の変更
9
- バグ修正（DECISIONS.mdではなくgit logで追跡）
10
- コメント追加・ドキュメント更新

学んだこと

1. 「却下した理由」を記録するのが最も価値が高い

「採用した理由」は実装を見ればわかることが多いです。しかし「なぜこの方式を採用しなかったか」は、記録しないと失われます。ADRの「コンテキスト」と「注意事項」が、AIの再提案を防ぎます。

2. ADRは5件で十分効果がある

全ての設計判断を記録する必要はありません。プロジェクトの中核となる3〜5件の判断を記録するだけで、AIとの開発の一貫性が大幅に改善しました。

3. 「注意事項」セクションがAI向けの指示になる

ADRの「注意事項」は本来、将来の人間開発者向けです。しかしCLAUDE.md経由でAIにも読ませることで、「このコードパターンは使うな」という指示として機能します。

まとめ

ADRをAI駆動開発で活用するポイントは以下の3点です。

「却下した設計」を記録: AIが同じ提案を繰り返すのを防止。「なぜやらないか」が最も重要
CLAUDE.mdから参照: 「設計変更前にDECISIONS.mdを確認する」ルールでAIに自動参照させる
注意事項をAI指示として活用: 「この実装パターンは使うな」を具体的なコード例付きで記載