Claude Codeで大規模コードベースを素早く把握するテクニック

新しいプロジェクトに参加したとき、数万〜数十万行のコードベースを理解するのに何日もかかることがあります。Claude Code を使えば、数分で全体像を把握できます。本記事では、大規模コードベースを効率的にナビゲートするテクニックを紹介します。

1. プロジェクト全体の概要を一発で掴む

最初にやるべきは、Claude Code にプロジェクト全体を俯瞰させることです。

claude -p "
このプロジェクトの全体構造を解説してください。
以下を含めてください:
- ディレクトリ構成とそれぞれの役割
- 使用している技術スタック
- エントリーポイント（起動の流れ）
- 主要なデータフロー
- 設定ファイルの役割
"

数秒で、README を読むよりも正確な「プロジェクト地図」が手に入ります。

2. 依存関係を可視化する

特定のモジュールがどこから呼ばれているかを調べるのは、大規模プロジェクトの最大の課題です。

claude -p "
src/services/AuthService.ts が以下のどのファイルから
import されているか調べてください。
呼び出しの深さ（直接/間接）も含めてリストアップしてください。
"

grepだけでは追えない間接的な依存関係も、Claude Code はコードを読んで理解してくれます。

3. コードの歴史を理解する

Gitの履歴と組み合わせると、「なぜこうなっているのか」がわかります。

git log --oneline -20 -- src/auth/ | claude -p "
このファイル群の直近20コミットから、
認証機能がどう進化してきたか要約してください。
特に設計変更があった箇所を中心に。
"

4. 重要ファイルを特定する

10万行のプロジェクトでも、本当に重要なファイルは20〜30個です。それを見つけます。

claude -p "
このプロジェクトで最も重要なファイルを10個選んで、
それぞれの役割と他のファイルへの影響度を説明してください。
変更するときにリスクが高いファイル順に並べてください。
"

これで「触ってはいけないファイル」と「安全に変更できるファイル」がわかります。

5. 設計パターンを読み取る

プロジェクトで使われている設計パターンを理解すると、新しいコードも一貫性を持って書けます。

claude -p "
このプロジェクトで使われている設計パターンを特定してください。
- リポジトリパターン
- サービスレイヤー
- ファクトリーパターン
- Strategy
- Observer
などが使われていれば、具体的なファイルと実装箇所を示してください。
"

6. テストカバレッジの穴を見つける

テストが不足しているモジュールを特定します。

claude -p "
src/ 配下のモジュールのうち、対応するテストファイルが
存在しないものをリストアップしてください。
ビジネスロジックの重要度も考慮して、
テストを追加すべき優先順位を付けてください。
"

カバレッジレポートを使わなくても、構造的な穴が見えます。詳しくは Claude Code テスト戦略 も参照。

7. サブエージェントで並列調査

大規模プロジェクトでは、複数のディレクトリを同時に調査するのが効率的です。

以下の3つを並列でサブエージェントに調査させてください:
1. src/api/ のエンドポイント一覧と認証方式
2. src/models/ のデータモデルとリレーション
3. src/middleware/ のミドルウェアチェーン

それぞれ要約して返してください。

メインのコンテキストを汚さずに、3倍速で調査できます。詳しくは サブエージェント活用パターン を参照。

8. CLAUDE.md で「地図」を残す

把握した情報を CLAUDE.md に書いておけば、次回以降は一瞬でコンテキストが復元されます。

# プロジェクト構造メモ

## エントリーポイント
- src/index.ts → Express サーバー起動
- src/app.ts → ルーティング定義

## 重要モジュール
- src/services/AuthService.ts → 認証の中核、変更時は注意
- src/repositories/ → DB アクセス層、Prisma 使用
- src/middleware/auth.ts → JWT 検証

## データフロー
リクエスト → middleware → controller → service → repository → DB

## 既知の技術的負債
- src/legacy/ はリファクタ中、触らない
- src/utils/helpers.ts は God Object 化している

CLAUDE.md ベストプラクティス も参考に。

まとめ

• プロジェクト全体を一発で俯瞰する
• 依存関係を直接/間接で可視化する
• Gitの歴史から設計の背景を理解する
• 重要ファイルとリスクを特定する
• 設計パターンを読み取って一貫性を保つ
• テストの穴を構造的に見つける
• サブエージェントで並列調査して時短
• CLAUDE.md に「地図」を残して資産化

大規模コードベースは「読む」のではなく「Claude Code に聞く」のが2026年のスタンダードです。公式ドキュメントは Anthropic Claude Code を参照してください。