はじめに
「なぜ認証にJWTを使っているんですか？」「......前任者が決めたみたいで、誰も理由を知らないんです」
このやり取りは、ソフトウェア開発チームのあちこちで繰り返されている。技術的な判断はコードに残っても、判断の理由はコードに残らない。
ADR（Architecture Decision Record）の自動生成という話は以前に触れたことがある。本記事のテーマはそこではなく、ADRをAIのコンテキストとして機能させることでClaude Codeのアーキテクチャ一貫性を担保するという話だ。Claude Codeはセッションをまたぐたびに記憶を失う。ADRはその問題への構造的な解答になる。
「なぜ」が消えることの4つのコスト
設計理由が残らないと、じわじわとコストがかかり続ける。同じ判断を繰り返し議論する（「またこの話か」）。「とりあえず現状維持」という停滞。新入りが理由を知らずにコードを修正してアーキテクチャが少しずつ崩れていく。そしてClaude Codeへの指示のたびに同じ背景を一から説明する繰り返し——これは使い込むほど地味に消耗する。
特に最後の問題は、Claude Codeを使うほど深刻になる。セッションが始まるたびに「なぜこのアーキテクチャか」を説明するのは非効率だ。ADRはこの問題の解決策でもある。
ADRの基本：「なぜ」を記録するフォーマット
ADR（Architecture Decision Record）はアーキテクチャの重要な決定を文書化するプラクティスだ。典型的なフォーマットはこうなる。
# ADR-001: 認証にJWTを採用する
背景・コンテキスト
ECサイトリニューアルで、マイクロサービス間の認証方式を決定する必要があった。
決定事項
JWTをベースのステートレス認証を採用する。
検討した代替案
- セッションベース認証: スケールアウト時にセッションストレージが必要
- OAuth2のみ: サードパーティ依存が強くなる
トレードオフ
- 採用の理由: ステートレスでスケールしやすい。マイクロサービス間の認証が容易
- 懸念点: トークン無効化が即時にできない
作成日: 2026-03-15 / 担当: 田中太郎
コードを読めば「何を」やっているかは分かる。ADRがあって初めて「なぜ」が分かる。
`.claude/adr/`ディレクトリ：ADRをAIのコンテキストにする
GitHubのClaude Code公式リポジトリにFeature Request Issue #13853として提案されている設計パターンがある（2026年4月現在、正式実装の有無は要確認）。提案内容は「`.claude/adr/`ディレクトリに配置したADRをClaude Codeが自動的に参照する」というものだ。
.claude/
├── adr/
│ ├── 001-jwt-authentication.md
│ ├── 002-postgresql-over-dynamodb.md
│ └── 003-nextjs-app-router.md
└── commands/
└── create-adr.md
正式実装を待たずとも、CLAUDE.mdからADRへの参照を明示することで同等の効果が得られる。
## アーキテクチャ決定（要約）
詳細はdocs/adr/を参照。主要な判断：
- 認証: JWT（詳細: docs/adr/001-jwt.md）
- DB: PostgreSQL（詳細: docs/adr/002-database.md）
- フロント: Next.js App Router（詳細: docs/adr/003-frontend.md）
変更が必要な場合はADRを更新してから実装すること。
このパターンでClaude Codeは「JWTを変更したい」という依頼を受けると、ADR-001を参照して「既存の決定とのトレードオフを考慮します」と応答するようになる。
二層構造：CLAUDE.md + docs/adr/
CLAUDE.mdにすべてのADRを詰め込もうとして、コンテキストウィンドウがすぐ溢れた。落ち着いたのが二層構造だ。
Layer 1: CLAUDE.md（作業記憶・60行以内）はセッション開始時に自動注入される。ここには主要なアーキテクチャ判断の要約だけを置き、詳細へのパスを示す。
Layer 2: docs/adr/（長期記憶・オンデマンド参照）にはClaude Codeが必要に応じて参照しに行く完全なADRを格納する。背景・代替案・トレードオフ・結論をすべて含める。
この構造によりCLAUDE.mdを60行以内に保ちながら、詳細な設計判断はオンデマンドでAIが参照できる。
ADRの自動生成：PRのdiffから記録を作る
設計判断が含まれるPRをマージするたびにADRを手動で書くのはコストが高い。Claude CodeにPR差分を分析させて自動生成するワークフローが実践されている。
# .claude/commands/generate-adr-from-pr.md
PRの差分を分析して、アーキテクチャ上の判断が含まれている場合にADRを生成してください：
1. `gh pr diff [PR番号]` を実行
2. 以下のパターンを検出したらADRを生成：
- 新しいライブラリ・フレームワークの追加
- データベーススキーマの重要な変更
- APIの設計変更
- 認証・認可の変更
3. docs/adr/ に連番で保存
4. CLAUDE.mdの「アーキテクチャ決定要約」セクションを更新
検出しなかった場合は「ADR不要と判断しました」と報告してください。
また、mcpmarket.comなどのスキルマーケットで公開されている「ADR Creator」スキルを使うと、会話からADRを生成してMADR（Markdown Architectural Decision Record）テンプレート形式で連番管理するところまで自動化できる。
Any Decision Record：EMへの応用
ADRの概念を「アーキテクチャ決定」から「あらゆる決定」に拡張する実践がある。
| ADR（Architecture Decision Record） | ADR（Any Decision Record） |
|---|---|
| アーキテクチャの決定のみ | あらゆる決定を記録 |
| 技術的な判断に限定 | ビジネス判断も含む |
| アーキテクトが主に記録 | 全メンバーが記録 |
EMへの応用例としては、評価制度の変更・採用基準の策定・会議体の新設・廃止・組織構造の変更などがある。
カオナビでは「今度こういう改善をしますと告知→1ヶ月掲示→文句があったら言ってください→『知らないとは言わせない』」という形でADRをチームのサイロを壊す道具として使っている実践がある。「立派な名前がついていないとみんな認めてくれない。ADRという名前があると真剣に受け止められる」という点も興味深い。
Hacobuのエンジニアリング事例によると、1年間で130件のADR作成（月平均10件以上）を達成し、AIを活用した過去ADRの検索・参照も実施しているという。
CLAUDE.mdへのADRガードレール組み込み
## アーキテクチャ変更のルール
変更前にADRを確認すること
以下の変更をする前に必ず docs/adr/ を確認し、既存の決定と矛盾がないかチェック：
- 認証・認可方式の変更
- データベース設計の変更
- 新ライブラリの追加
ADRが必要な変更
以下の場合は変更前にADRを作成し、私の承認を得ること：
- 既存のADRを覆す変更
- アーキテクチャに大きな影響を与える新規判断
ADRの更新
既存の決定が変更された場合、該当するADRに「Superseded by ADR-XXX」を追記すること。
古いADRは削除しない（判断の歴史を残す）。
まとめ
ADRを書き始めてから、Claude Codeが「この決定の背景を知っているか」という前提で動くようになった実感がある。コードだけ渡しても「何をしているか」しか分からない。「なぜそうなのか」を渡して初めて、一貫したアーキテクチャの判断が返ってくる。
今すぐ（15分）：プロジェクトで最近最も議論を呼んだ技術判断を1つ選び、Claude Codeに「この判断をADRの形式で文書化して」と依頼する。`docs/adr/001-xxx.md`に保存する。
今日中：CLAUDE.mdに「アーキテクチャ決定要約」セクションを追加し、既存の主要な技術判断を3〜5項目と詳細ファイルへのパスを記録する。
今週：`.claude/commands/generate-adr-from-pr.md`を作成し、次回のPRマージ時にADR自動生成を試す。
コメント