大きなコードベースをClaude Codeに理解させる手順

新しい職場で渡された数十万行のリポジトリ。あるいは外部からメンテを引き継いだ古いプロジェクト。こういう状況でClaude Codeに「中身を全部読んで」と言うのは最悪の使い方です。読みすぎてコンテキストが破綻するか、表面的な要約だけで終わります。本記事では、既存の大規模コードを「使える理解度」まで持っていく実用手順を整理します。

結論：「入口→外周→深掘り」の3段で読ませる

未知のコードを理解させるときの順序はこうです。

1. 入口を特定する（10分）：エントリポイント・主要設定・パッケージ構造を人間が手で特定
2. 外周を一周する（30〜60分）：サブエージェントに「読まずに列挙」させ、NOTES.mdに地図を作る
3. 深掘りする（タスク発生時のみ）：触る領域だけを精読し、用語集と意思決定ログに残す

最初の2段で全文は読ませないのがコツです。AIに「全部読んで把握して」と頼んだ瞬間、コンテキストが埋まり精度が落ちます。「読ませない設計」の全体像は「Claude Codeに必要な情報だけ渡すコンテキスト設計」、大規模特有のコンテキスト運用は「Claude Codeで長い会話や大きなリポジトリを扱うコンテキスト管理術」を参照してください。

ステップ1：入口を人間が10分で特定する

AIに任せず、人間が手で5項目だけ確定させます。これだけでClaude Codeの当てずっぽうが激減します。

確認できたら、ルートCLAUDE.mdに1〜2行ずつ書きます。

## このリポジトリ
- 言語: TypeScript（pnpm workspaces）
- 起動: `pnpm dev`（apps/web, apps/api を並列起動）
- テスト: `pnpm test`（vitest）
- エントリポイント: apps/web/src/app/, apps/api/src/index.ts
- デプロイ: GitHub Actions → Vercel/Render

CLAUDE.md自体の構造は「CLAUDE.mdテンプレート完全版」、リポジトリ構成の整理は「Claude Codeでプロジェクトを読ませる前に整理すべきファイル構成」を参照してください。

ステップ2：サブエージェントに「外周」を描かせる

人間が入口を確定したら、ここからAIに任せます。コツは読み込まず列挙だけさせることです。

2-1. ディレクトリマップ作成

依頼:
Explore サブエージェントで以下を実行してください。

1. リポジトリのトップレベル構成を rg と ls だけで把握
2. 各ディレクトリの「役割を1行で説明」
3. ファイル数とおおよそのコード量
4. 結果を NOTES/MAP.md に Markdown 表で書き出す
5. ファイル本文は読まないでよい

Exploreは読み取り専用・Haikuベースなので、広く浅く走らせるのに向きます。設計は「Claude Codeのサブエージェントとは？使いどころと注意点」を参照してください。

2-2. 入口関数の依存関係

主要エントリポイントから「誰が呼んで、何を呼んでいるか」だけを列挙させます。

依頼:
apps/api/src/index.ts から始めて、以下を NOTES/CALLGRAPH.md に書き出してください。

1. ルーティング定義の一覧（パスとハンドラ関数名）
2. 各ハンドラが import している主要モジュール（外部ライブラリは除く）
3. 「DBアクセスする」「外部APIを呼ぶ」「課金処理を含む」をフラグとしてマーク
4. 中身のロジックは読まないでよい。シグネチャと import 文だけで十分

これで「どのエンドポイントを触ると怖いか」「どこが脆弱性監査の対象か」がファイルを1つも開かずに把握できます。

2-3. 用語集の抽出

「Tenant」「Subscription」「Workspace」「Member」「Org」みたいなドメイン語が乱立しているリポジトリでは、用語集が早期理解の最大レバレッジです。

依頼:
リポジトリ全体から型定義・スキーマ・ER図を rg で拾い、
ドメイン用語を NOTES/GLOSSARY.md に整理してください。

各エントリは以下のフォーマット:
- 用語名
- 1行説明（型定義から推測）
- 関連する別用語（同義語・包含関係）
- 主な出現箇所（最大3ファイル）

推測できないものは「要確認」とだけ書く。

NOTES/GLOSSARY.mdはチームでもレビュー対象になり得る成果物です。AIにすべてを書かせず、認識違いは人間が修正します。

ステップ3：触る領域だけ深掘りする

地図と用語集ができたら、特定タスクのときだけ精読します。原則は**「読ませる範囲は1〜3ファイル」**です。

3-1. 質問駆動で深掘り

「全部理解して」ではなく具体的な質問にします。

依頼文の骨格は「Claude Codeに伝わるプロンプトの基本構造」、悪い依頼の改善例は「Claude Codeでやりがちな悪い依頼文と改善例」を参照してください。

3-2. 「読まずに済む」ものは読まない

次のものは原則として読ませません。

• テストフィクスチャ、スナップショット、生成物（__generated__/）
• ベンダー製品の同梱（vendor/ third_party/）
• マイグレーションファイル群（数百個に膨れがち）
• ロックファイル（pnpm-lock.yaml、Cargo.lock等）
• ロゴ・スクリーンショット等のバイナリ

claudeMdExcludesで物理的に塞ぐと、@参照しても無視されます。設定例は「Claude Codeで長い会話や大きなリポジトリを扱うコンテキスト管理術」を参照してください。

3-3. テストから入る読み方

実装より先にテストを読ませると、AIは「期待される振る舞い」の解像度を保ったまま実装を見られます。

ヒットしたテストファイルだけ@で渡し、「このテストが要求する仕様を箇条書きで」と頼みます。実装本体はそのあとに渡します。

調査依頼テンプレ4本

A. 1機能の責務サマリ

## 入力
- 対象: @<対象ファイル>

## 出力
1. この関数/モジュールの責務を1段落で
2. 入力と出力のペア（型まで含めて）
3. 副作用（DB／外部API／ファイルIO）
4. 依存している外部モジュール
5. テストが網羅していない可能性が高い分岐

## 禁止
- 改善提案は今出さない（次の依頼で扱う）
- 推測で書かない。読めなければ「不明」と記載

B. 影響範囲調査（変更の影響）

## 入力
- 変更予定: `UserService.createUser` のシグネチャに organizationId を追加

## 出力
1. 直接の呼び出し元（ファイル＋行）
2. 間接的に影響を受けるルート（ルーティング名）
3. テストで触れている箇所
4. ドキュメントで言及されている箇所

## 制約
- 列挙のみ。修正はしない
- まず rg で grep してから読む

C. アーキテクチャの一段抽象化

## 入力
- @NOTES/MAP.md @NOTES/CALLGRAPH.md

## 出力
1. レイヤー構造（presentation/application/domain/infrastructure 等の現状認識）
2. レイヤー違反の疑いがある依存（実装ではなく可能性のリスト）
3. 命名規則と例外
4. 今後変更しないと負債が膨らみそうな箇所（推測でよい。根拠を必ず書く）

D. オンボーディングQ&A生成

## 入力
- @CLAUDE.md @NOTES/MAP.md @NOTES/GLOSSARY.md

## 出力
新メンバーが最初の2週間で詰まりそうな質問を 10 個生成してください。
各質問に対して、答えがどのファイル/ドキュメントを読めば分かるかも書いてください。
答えが不明なものは「要確認」とだけ書く。

オンボーディングへの応用は「新人メンバーにClaude Codeを安全に使ってもらうオンボーディング」を併読してください。

アンチパターン

読ませる前のチェックリスト

• パッケージマネージャ・起動・テスト・主要エントリポイント・CIをルートCLAUDE.mdに書いた
• claudeMdExcludesで生成物・成果物・サードパーティを除外した
• サブエージェントでNOTES/MAP.md（ディレクトリ地図）を作った
• サブエージェントでNOTES/CALLGRAPH.md（主要関数の依存）を作った
• サブエージェントでNOTES/GLOSSARY.md（用語集）を作り、人間が見直した
• 質問は「全体理解」ではなく具体的な対象とアウトプット形式に絞った
• テスト→実装の順で読ませる依頼パターンを使っている
• 領域ごとにセッションを分け、/clearで切り替えている

次に読むおすすめ記事：

• 「Claude Codeで長い会話や大きなリポジトリを扱うコンテキスト管理術」：1日の運用とNOTES.md設計
• 「Claude Codeのサブエージェントとは？使いどころと注意点」：ExploreとPlanの使い分け
• 「Claude Codeでプロジェクトを読ませる前に整理すべきファイル構成」：3層モデルと触らない領域