プロジェクトが成長するにつれて、「なぜこの設計を選んだのか」が失われる問題は、ほとんどすべての開発チームが直面する課題です。新しいメンバーがコードを見ても、その背景にある判断理由はコードから読み取れません。アーキテクチャ決定記録（ADR: Architecture Decision Records）はこの問題を解決する軽量なドキュメンテーション手法であり、Claude Codeとの相性は抜群です。
本記事では、Claude Codeを使ってADRをチームに導入し、設計判断の可視化・共有・レビューを自動化する実践的な手法を解説します。ADRの基本から、Claude Codeによるテンプレート生成、Git管理との統合、既存コードベースからのADR逆生成まで、すぐに使える具体的な手順をお届けします。
この記事でわかること
- ADRの基本概念と、なぜAI時代に重要性が増しているか
- Claude CodeでADRをゼロから導入する5ステップ
- ADRテンプレートの自動生成とカスタマイズ方法
- 既存コードベースからADRを自動生成する逆変換手法
- Git管理・レビュー自動化を含む運用ワークフロー
- チーム導入時に発生する課題と解決策
ADRとは何か——設計判断の「なぜ」を残す技術
ADR（Architecture Decision Record）は、ソフトウェアアーキテクチャに関する重要な決定と、その背景にある理由を記録する軽量なドキュメント形式です。Michael Nygardが2011年に提唱し、現在ではThoughtWorksのTechnology Radarでも「採用（Adopt）」と評価されている成熟したプラクティスです。
ADRが解決する3つの問題
1. 暗黙知の喪失——「なぜマイクロサービスではなくモジュラーモノリスにしたのか」という判断は、半年後には誰も覚えていません。ADRがあれば、新人も外部ベンダーも即座に背景を理解できます。
2. 同じ議論の繰り返し——過去に検討済みの選択肢について、新しいメンバーが参加するたびに同じ議論が再燃します。ADRは「すでに決定済み」のエビデンスとして機能します。
3. コンテキストスイッチのコスト——コードレビューで「なぜこの設計？」と聞かれるたびに、Slackや口頭で長文の説明をする必要がなくなります。ADRへのリンクを貼るだけで完了です。
ADRの基本構造
標準的なADRは以下の5セクションで構成されます：
# タイトル: [決定内容を簡潔に]
## ステータス
提案中 / 承認済み / 廃止 / 差し替え済み
## コンテキスト
この決定が必要になった背景、制約条件、ビジネス要件
## 決定
実際に行ったアーキテクチャ上の選択
## 結果
この決定によって生じるポジティブな影響とネガティブな影響
## 代替案
検討したが採用しなかった選択肢とその理由この構造はシンプルですが、チームの設計判断を体系的に蓄積するには十分です。そして、この定型フォーマットこそがClaude Codeの得意領域です。
なぜClaude CodeとADRは相性が良いのか
ADRは「定型フォーマットへの構造化された記述」と「コードベースの深い理解」の両方を必要とします。これはまさにClaude Codeが最も得意とする作業です。
Claude CodeがADR運用にもたらす3つの価値
1. テンプレートの自動生成と遵守——Claude Codeに「新しいADRを書いて」と指示するだけで、標準フォーマットに従った下書きを生成できます。人間がフォーマットを覚える必要はありません。
2. コードベースを理解した上での提案——Claude Codeはプロジェクトのコードを読めるため、「このコードベースではすでにRedisをキャッシュ層に使っているので、メッセージキューにもRedis Streamsを選ぶADR」といった、コンテキストを踏まえた提案が可能です。
3. 既存コードからのADR逆生成——これは特に強力です。過去の設計判断がドキュメント化されていないコードベースに対して、Claude Codeに「このプロジェクトのアーキテクチャ決定をADRとして書き出して」と指示すれば、コードから判断を推論してADRを生成できます。
Claude Codeの概要ドキュメントで説明されているコードベース理解能力と、Common Workflowsのベストプラクティスを組み合わせることで、ADRの作成・管理・レビューを効率的に自動化できます。
ステップ1：Claude CodeでADRテンプレートを生成する
最初のステップは、チーム標準のADRテンプレートをClaude Codeで生成することです。プロジェクト直下のdocs/adr/ディレクトリにテンプレートを配置するのが一般的です。
Claude Codeへの指示例
プロジェクトの docs/adr/ ディレクトリに、ADR（Architecture Decision Record）の
テンプレートを作成してください。
要件:
- 日本語で記述
- Michael Nygard形式に準拠（タイトル、ステータス、コンテキスト、決定、結果、代替案）
- ステータスは「提案中」「承認済み」「廃止」「差し替え済み」の4種類
- フロントマターに作成日と決定者のフィールドを含める
- ファイル名は NNNN-title-with-dashes.md 形式
- 番号は連番で、既存のADRを自動検出して次の番号を割り当てる
- docs/adr/README.md にADR一覧のインデックスも生成するClaude Codeはプロジェクトのdocs/adr/を調べ、既存のADRがあればその番号を確認し、新しいADRのテンプレートとREADMEインデックスを同時に生成します。この一連の作業を、人間が手動で行う場合の1/10以下の時間で完了できます。
生成されるテンプレート例
---
date: 2026-06-12
decision_makers: ["チーム名"]
status: 提案中
---
# ADR-0004: [決定内容の簡潔なタイトル]
## ステータス
提案中
## コンテキスト
[この決定が必要になった背景、技術的制約、ビジネス要件を記述]
## 決定
[実際に行ったアーキテクチャ上の選択とその理由]
## 結果
### ポジティブな影響
- [期待される改善点]
### ネガティブな影響
- [想定されるトレードオフやリスク]
## 代替案
### 代替案1: [検討した別の選択肢]
- メリット: [利点]
- 不採用理由: [なぜ選ばなかったか]
## 参考
- [関連するドキュメントや議論へのリンク]ステップ2：設計判断をADRとして記録する
テンプレートが整ったら、実際の設計判断をADRとして記録します。ここでは、Claude Codeに現在のコードベースと設計課題を読ませた上でADRを生成させる方法が効果的です。
典型的なユースケース：認証方式の選定
実際のプロジェクトでよくある設計判断を例に、Claude Codeを使ったADR作成の流れを見てみましょう。
このプロジェクトの認証方式についてADRを作成してください。
状況:
- 現在はセッションベースの認証を使っている
- モバイルアプリ対応のため、トークンベースへの移行を検討中
- 既存ユーザーへの影響を最小限にしたい
以下の観点で分析し、ADRにまとめてください:
- JWT vs セッショントークン の比較
- 現在のコードベースの auth/ ディレクトリを読んだ上での移行コスト見積もり
- セキュリティ上の考慮点
- 推奨するアプローチと移行計画Claude Codeは認証関連のコードを分析し、既存のセッション管理の実装を理解した上で、JWTへの移行に関するADRを生成します。単なるテンプレート穴埋めではなく、実際のコードベースを踏まえた具体的な内容になります。
Claude Codeが自動で行うこと
auth/ディレクトリ以下のコードを解析し、現在の認証フローを理解- セッション管理の実装箇所を特定し、移行時の修正範囲を見積もる
- ADRテンプレートに沿って、コンテキスト・決定・結果・代替案を埋める
- 適切なファイル名（
0005-jwt-authentication-migration.mdなど）で保存 README.mdのADRインデックスを更新
ステップ3：既存コードベースからADRを逆生成する
すでに稼働しているプロジェクトで、設計判断がドキュメント化されていない場合、Claude Codeのコード理解能力を活用してADRを逆生成できます。これは「アーキテクチャの考古学」とも呼べるアプローチです。
逆生成の指示例
このプロジェクトの主要なアーキテクチャ決定をADRとして逆生成してください。
手順:
1. まず package.json, tsconfig.json, Dockerfile, docker-compose.yml などの
設定ファイルを読み取り、採用技術スタックを特定する
2. src/ 以下のディレクトリ構成から、アーキテクチャパターンを推論する
（モノリス/マイクロサービス/モジュラーモノリス など）
3. 依存関係（package.json の dependencies）から技術選定の意図を推論する
4. 以下の観点でADRを生成する:
- フロントエンドフレームワークの選定理由
- 状態管理ライブラリの選定理由
- バックエンドアーキテクチャの選定理由
- データベース選定理由
- コンテナ化の方針
5. 各ADRは推論ベースであることを「ステータス: 提案中（逆生成）」と明記する
6. docs/adr/ に保存し、READMEインデックスを更新するこのアプローチの利点は、既存プロジェクトの「暗黙のアーキテクチャ決定」を可視化できることです。生成されたADRは推論ベースなので、必ずチームでレビューして承認する必要がありますが、ゼロから書くよりはるかに効率的です。
逆生成ADRの注意点
- 推論の限界を明示する——Claude Codeがコードから読み取った推論は、実際の決定理由と異なる可能性があります。「ステータス: 提案中（逆生成）」として、人間の確認を必須にします。
- 優先順位をつける——すべてのコードパターンをADR化する必要はありません。アーキテクチャ全体に影響する大きな決定（フレームワーク選定、データストア選定、通信方式など）に絞ります。
- Git blameと組み合わせる——コードの導入時期や担当者をgit blameで確認し、当時のコンテキストを補完することで、より正確なADRに近づけます。
ステップ4：ADRをGit管理に組み込む
ADRはコードと同様にバージョン管理することが重要です。Claude Codeを使えば、ADRのGit管理を以下のように自動化できます。
Claude Codeに任せるGit操作
新しいADR（docs/adr/0005-jwt-authentication-migration.md）を作成したので、
以下のGit操作を行ってください:
1. git add docs/adr/0005-jwt-authentication-migration.md docs/adr/README.md
2. 適切なコミットメッセージを生成して git commit
（形式: "docs(adr): JWT認証への移行を提案 [ADR-0005]"）
3. ブランチを作成し、プッシュ
4. PRを作成し、レビュアーとして @team-leads をアサイン
5. PRの説明文に、ADRの要約と判断理由を自動生成ここで特に便利なのは、Claude CodeがADRの内容を読んだ上で、適切なコミットメッセージとPR説明文を自動生成できる点です。人間がADRを書いた後に、さらにコミットメッセージとPR説明を書く二度手間が省けます。
ADRレビューの観点
PRとして提出されたADRは、以下の観点でレビューします。Claude Codeに「このADRをレビューして」と指示することで、事前チェックも自動化できます。
- コンテキストの十分性——この決定が必要になった背景が、チーム外の人が読んでも理解できるか
- 代替案の網羅性——検討すべき主要な代替案が列挙されているか
- トレードオフの明示——ポジティブな影響だけでなく、ネガティブな影響も正直に書かれているか
- 参照の正確性——引用されているドキュメントや議論へのリンクが有効か
ステップ5：ADRの定期的な棚卸しとメンテナンス
ADRは「書いて終わり」ではありません。時間の経過とともに状況が変わり、古い決定を見直す必要が出てきます。Claude Codeを使えば、定期的なADR棚卸しも自動化できます。
定期的な棚卸しの自動化
docs/adr/ ディレクトリ内のすべてのADRを確認し、以下の棚卸しを行ってください:
1. 各ADRのステータスを確認し、6ヶ月以上更新がないものをリストアップ
2. 「承認済み」のADRのうち、以下の条件に該当するものを特定:
- 参照しているライブラリが現在の package.json に存在しない
- コードベースの実装がADRの記述と矛盾している
3. 棚卸し結果を docs/adr/AUDIT-2026-06.md にまとめる
4. 更新が必要なADRについては、「差し替え」の提案ADRを下書きするこの定期メンテナンスをClaude Codeに任せることで、ADRが「書いただけで更新されない死んだドキュメント」になるのを防げます。Claude Codeのベストプラクティスにある「繰り返し作業の自動化」の考え方をADR運用に適用した形です。
Claude Code × ADR 運用のベストプラクティス
実際にチームで運用する際に効果的だったパターンを共有します。
1. CLAUDE.md にADRルールを定義する
プロジェクトのCLAUDE.mdにADRに関する指示を書いておくことで、Claude Codeが常にADR運用ルールを認識した状態で動作します。
## ADR（Architecture Decision Records）運用ルール
- 新しいアーキテクチャ上の決定を行った場合は、必ずADRを作成すること
- ADRは docs/adr/ に配置し、NNNN-title-with-dashes.md 形式で命名
- ステータスは「提案中」「承認済み」「廃止」「差し替え済み」の4種類
- 重要な設計判断を行うPRには、必ずADRを添付するか、既存ADRへの参照を含める
- ADRの承認には、チームリード最低1名のApproveが必要
- 承認済みADRの棚卸しを月1回実施し、AUDITレポートを生成する
参考:
- ADRテンプレート: docs/adr/template.md
- ADR一覧: docs/adr/README.md
- ADRの書き方: https://github.com/joelparkerhenderson/architecture-decision-recordCLAUDE.mdの設定方法については、CLAUDE.md設計・運用ガイドの記事も参考にしてください。
2. HooksでADRの作成を自動検知する
Claude CodeのHooks機能を使うと、特定のイベントに応じて自動的にADR作成を促せます。たとえば、新しい依存関係が追加されたときにADRの下書きを自動提案するHookを設定できます。
# .claude/hooks/on-dependency-change.sh
#!/bin/bash
# package.json の dependencies が変更されたら、ADR作成を提案
echo "新しい依存関係が追加されました。"
echo "該当するADRの作成/更新が必要か確認してください。"
echo "Claude Codeに「この依存関係追加に関するADRを作成して」と指示してください。"Hooksの詳細な設定方法は、Claude Code Hooks実践ガイドを参照してください。
3. 既存ADRとの整合性チェック
新しいコード変更が既存のADRと矛盾していないかをClaude Codeにチェックさせる習慣をつけると、アーキテクチャの一貫性を保てます。
このPRの変更内容と、docs/adr/ 以下のすべてのADRを比較してください。
以下の観点で矛盾がないかチェックし、結果を報告してください:
1. ADRで決定された技術スタックから逸脱していないか
2. ADRで「不採用」とされた技術を新たに導入していないか
3. ADRの「結果」セクションで予測されたリスクが顕在化していないかよくある課題と解決策
課題1：「ADRを書く時間がない」
解決策——Claude Codeに任せましょう。設計判断の要点を口頭で伝えるだけで、フォーマットに沿ったADRの初稿を生成できます。人間はレビューと修正に集中すればよく、執筆時間は従来の1/5以下になります。
課題2：「形式的すぎて誰も読まなくなる」
解決策——「ADRは議事録ではない」という認識を共有します。すべての議論をADR化するのではなく、アーキテクチャ全体に影響する決定だけを対象にします。目安として、1プロジェクトあたり20〜30件程度が適正量です。
課題3：「古いADRがそのまま放置される」
解決策——ステップ5で紹介した定期棚卸しを自動化します。Claude Codeに月次でADRの鮮度チェックを実行させ、更新が必要なものをリストアップさせることで、メンテナンスの負荷を下げられます。
課題4：「ADRとコードの同期が取れなくなる」
解決策——PRテンプレートに「ADRチェック」項目を追加し、コードレビューの一部としてADRの更新有無を確認する習慣をつけます。Claude Codeのコードレビュー効率化ガイドで紹介されている手法と組み合わせると効果的です。
まとめ：AI時代のADR運用はClaude Codeで自動化する
ADRは決して新しい概念ではありませんが、Claude CodeのようなAIコーディングツールの登場によって、その運用効率は飛躍的に向上しました。テンプレート生成、コードベースを理解した上でのADR作成、既存コードからの逆生成、Git管理との統合、定期棚卸し——これらすべてをClaude Codeがサポートします。
重要なのは、「ADRを書くこと」が目的ではなく、「設計判断を可視化してチームの意思決定品質を上げること」が目的だという点です。Claude CodeはADR作成の手間を劇的に減らすことで、チームが本質的な設計議論に集中できる環境を作ります。
まずは小さく始めましょう。今日から、次の設計判断をClaude CodeでADR化してみてください。その1枚のADRが、半年後のチームを救うかもしれません。
Claude Codeの導入・運用についてご相談ください
Claude Codeを使った開発プロセスの効率化や、ADRを含むドキュメンテーション戦略について、UravationのAIコンサルタントがご支援します。チーム規模や業種を問わず、最適な導入プランをご提案します。
実践事例：5人チームでのADR導入プロセス
ここでは、実際に5人規模のWebアプリケーション開発チームがClaude Codeを使ってADRを導入した事例を紹介します。このチームはNext.js + NestJS + PostgreSQLの技術スタックでBtoB SaaSを開発しており、2年間の開発で設計判断が属人化していることが課題でした。
導入前の状況
導入前のこのチームでは、アーキテクチャに関する判断はすべて口頭またはSlackのスレッドで行われていました。「なぜPrismaではなくDrizzle ORMを選んだのか」「なぜRedisをセッションストアに使っているのか」といった情報は、在籍期間の長い2〜3名のエンジニアの頭の中にしかありませんでした。新しいメンバーがオンボーディングするたびに、同じ質問が繰り返され、説明する側の負担も増大していました。
Claude CodeでADRを導入した3週間
1週目：テンプレートと初期ADRの生成
まずClaude Codeにプロジェクトのdocs/adr/ディレクトリを作成させ、テンプレートとインデックスを生成しました。続いて、主要な技術選定（ORM、認証方式、API設計スタイル、テスト戦略）について、Claude Codeにコードベースを読ませた上でADRの初稿を生成させました。この時点で6件のADRが作成され、チーム内でSlackを使って非同期レビューを行いました。
2週目：レビューと承認プロセスの確立
生成されたADRに対して、チームメンバーがコメントを付け、Claude Codeに修正を指示する流れが定着しました。特に関心が高かったのは「なぜGraphQLではなくREST APIを選んだのか」というADRで、過去の議論を知らなかったメンバーから「この判断は正しかった」という納得の声が上がりました。CLAUDE.mdにADR運用ルールを追記し、新しい技術選定には必ずADRを添付するルールをチームで合意しました。
3週目：定期メンテナンスの自動化
Claude Codeに月次でのADR棚卸しを自動実行させるHookを設定しました。また、PRテンプレートに「ADRチェック」セクションを追加し、コードレビュー時に既存ADRとの整合性を確認する習慣を導入しました。3週間の時点でADRは12件に増え、チームメンバー全員が「必要な情報にすぐアクセスできるようになった」と評価しました。
導入後に得られた定性的効果
- オンボーディング時間の短縮——新メンバーがプロジェクトのアーキテクチャを理解するまでの時間が約60%短縮されました。ADRを読むだけで主要な設計判断の背景を把握できるようになったためです。
- 設計レビューの質的向上——「なぜこの設計にしたのか」という議論が、ADRを参照しながら行われるようになり、過去の決定を踏まえた建設的な議論が増えました。
- 属人性の解消——特定のメンバーにしかわからなかった設計判断が、ADRという形でチーム全体の共有資産になりました。退職や異動による knowledge loss のリスクが大幅に低減しました。
- 技術的負債の可視化——ADR棚卸しの過程で、「この決定は現在の状況に合わなくなっている」という気づきが生まれ、計画的なリファクタリングのきっかけになりました。
ADR運用を支えるClaude Codeの関連機能
ADR運用を効果的に進めるために、Claude Codeの以下の機能も活用できます。
Plan ModeでのADRレビュー計画
大規模なアーキテクチャ変更を伴う場合、まずClaude CodeのPlan Modeで変更計画を立て、その計画に基づいてADRを生成するアプローチが効果的です。Plan Modeを使うことで、変更の影響範囲を事前に特定し、どのADRを更新すべきかを体系的に洗い出せます。
カスタムスラッシュコマンドの活用
以下のようなカスタムスラッシュコマンドを設定しておくと、ADR作成がさらに効率的になります。
# .claude/commands/adr.md
新しいADRを作成してください。
手順:
1. docs/adr/ を確認し、次のADR番号を特定
2. テンプレートに沿ってADRを生成
3. docs/adr/README.md を更新
4. git add & git commit（適切なコミットメッセージで）
5. PRを作成するかどうかを確認このコマンドを /adr 認証方式をJWTに移行する のように使うことで、ADR作成からGit管理までをワンストップで実行できます。
サブエージェントを使った並列ADR生成
大規模プロジェクトで多数のADRを同時に生成する必要がある場合、Claude Codeのサブエージェント機能を使うと、複数のADRを並列で生成できます。たとえば、フロントエンド、バックエンド、インフラの3領域について、それぞれ別のサブエージェントにADR生成を指示することで、作業時間を1/3に短縮できます。
詳細な使い方は、Claude Codeサブエージェント並列開発入門を参照してください。
