Article

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

数万〜数十万行の既存リポジトリをClaude Codeに読ませて、設計判断や改修方針の相談に使えるレベルまで持っていく手順を整理します。入口ファイル特定、依存関係マップ、用語集、調査依頼テンプレ、読み込みすぎ防止までを実務目線で扱います。

This article is not published in this language yet, so the Japanese version is shown instead.

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

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

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

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

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

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

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

項目	探し方
パッケージマネージャ	`package.json` `pyproject.toml` `Cargo.toml` `go.mod`の有無
ビルド・実行コマンド	READMEの「Getting Started」、`Makefile`、`scripts/`、`package.json`の`scripts`
主要エントリポイント	`src/index.` `app/`配下、`main.`、APIなら`routes/`／`handlers/`
テストコマンド	`package.json`の`test`、`pytest.ini`、`go test`の運用
デプロイ・CI	`.github/workflows/`、`Dockerfile`、`Procfile`、`vercel.json`

確認できたら、ルート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. 質問駆動で深掘り

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

悪い依頼	良い依頼
billing 周りを全部理解して	apps/api/src/billing/checkout.ts の handleCheckout 関数の責務を1段落で説明して
認証どうなってる？	apps/web/src/middleware.ts と apps/api/src/auth/ の役割分担を比較表で出して
全体の設計を教えて	NOTES/MAP.md と CALLGRAPH.md を読んで、apps/api が DDD のどの層分けに近いか1段落で評価して

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

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

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

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

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

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

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

rg -l 'describe\\(.*billing' apps/api/src --type ts

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

調査依頼テンプレ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を安全に使ってもらうオンボーディング」を併読してください。

アンチパターン

ミス	何が起きる	対処
「全部読んで」	コンテキスト枯渇＋表層要約	入口→外周→深掘りの3段に分ける
`@apps/`を丸投げ	数万トークンを一発で消費	`rg`で絞ってから`@file`単発
マイグレーション全部読ませる	履歴が雑音になる	`claudeMdExcludes`で除外
一回の会話で全領域	コンテキスト混線	領域ごとにセッションを分ける
AIに用語を勝手に定義させる	嘘の用語が広がる	用語集は人間レビュー必須