はじめに
こんにちは。
開発部でエンジニアをしている西尾です。
Claude Codeは、Anthropicが提供するエージェント型のコーディング支援ツールです。ターミナル上で動作し、コードベースを自律的に探索しながら開発者の質問に答えたり、コードを生成・編集したりできます。
本記事では「Claude Codeは大規模なリポジトリをどこまで理解できるのか？」を確認すべく検証を行いました。
Claude Codeの通常モードとPlanモードの2つを比較し、タスクによってどちらが有効かも検証しました。
モード別の使い分け
検証の結果、Claude Codeの通常モードとPlanモードには明確な得意分野が存在することが分かりました。
| やりたいこと | 推奨モード |
|---|---|
| 影響範囲の特定、網羅的なリストアップ | Planモード |
| 複雑な仕組みの深い理解、詳細な説明 | 通常モード |
本記事では、この結論に至った詳細な検証プロセスと、両モードがFastAPIのような大規模リポジトリをどのように理解したかを解説します。
検証環境
| 項目 | 内容 |
|---|---|
| 対象リポジトリ | fastapi/fastapi |
| 言語 | Python（型ヒント活用） |
| 主要依存関係 | Starlette, Pydantic |
Claude Codeのモードについて
Claude CodeにはShift + Tabで切り替えられる複数のモードがあります。
| モード | 操作 | 特徴 |
|---|---|---|
| 通常モード | デフォルト | ファイル読み取り・編集・コマンド実行が可能 |
| Planモード | Shift+Tab 2回 | 読み取り専用、計画立案に特化 |
検証内容
4つの観点から、両モードの理解力を比較しました。それぞれ異なるタイプのタスクを設定し、モードによって回答の質や網羅性に差が出るかを検証します。
| 検証 | 目的 | 期待 |
|---|---|---|
| ①全体像の把握 | 初見のリポジトリを素早く理解できるか | Planモードは「計画」に特化しているため、構造把握も得意かもしれない |
| ②依存関係の追跡 | 特定の機能がどう実装されているか追えるか | 複数ファイルを横断する分析力を比較 |
| ③影響範囲の分析 | 変更前のリスク評価ができるか | Planモードは「計画立案」向けなので、影響分析に強いはず |
| ④複雑な仕組みの理解 | 抽象的な概念を体系的に説明できるか | 通常モードの方が詳細な説明に向いているかも |
各検証では、同じ質問を両モードに投げて回答を比較します。
検証結果
検証①：プロジェクト全体像の把握 — 両モードともExploreエージェントに委譲
質問：
このリポジトリの主要なディレクトリ構成と、それぞれの役割を説明して
結果比較
| 観点 | 通常モード | Planモード |
|---|---|---|
| 直接読んだファイル数 | 0件 | 0件 |
| 探索方法 | Exploreエージェントに委譲 | Exploreエージェントに委譲 |
| 報告したテストファイル数 | 417個 | 168以上 |
| 回答形式 | 箇条書き中心 | 表形式中心 |
通常モードの出力例（箇条書き中心）
各ディレクトリの役割
1. fastapi/ - コアフレームワーク
FastAPIの本体実装。主要モジュール:
- applications.py - FastAPI アプリケーションクラス
- routing.py - APIRouter とルーティングロジック
- params.py - Query, Path, Body 等のパラメータ定義
- dependencies/ - 依存性注入システム
- security/ - OAuth2、APIKey等の認証機能
...
Planモードの出力例（表形式中心）
調査結果をまとめます。
主要ディレクトリ構成
ディレクトリ 役割
fastapi/ コアソースコード。FastAPIフレームワーク本体
tests/ テストスイート（168以上のテストファイル）
docs/ ドキュメント（16言語対応：en, ja, zh など）
docs_src/ チュートリアル用サンプルコード（72カテゴリ）
scripts/ ビルド・テスト・ドキュメント自動化スクリプト
.github/ GitHub Actions ワークフロー、Issue テンプレート
また、Planモードは「情報提供のリクエストであり、実装計画が必要なタスクではない」と自己判断してモードを終了する様子も観察されました。
検証②：ファイル間の依存関係の追跡 — Planモードは表形式で整理された出力
質問：
Dependsはどこで定義されていて、実際にどのように処理されるか追跡して
結果比較
| 観点 | 通常モード | Planモード |
|---|---|---|
| Dependsクラスの行番号 | 765-768 | 765-769 |
| ラッパー関数の行番号 | 2221-2299 | 2221-2298 |
| フロー図 | あり | あり |
| 主要ファイル一覧 | 本文中に散在 | 表形式で整理 |
どちらのモードも、依存性注入の処理を正確に2フェーズに分けて説明しました。
回答の正確性は同等（行番号も1行の誤差程度）であり、
Planモードの方が整理されている：主要ファイル・関数を表形式でまとめる傾向にあります。
Planモードの出力例（表形式で整理）
1. Depends の定義場所
クラス定義: params.py:765-769
@dataclass(frozen=True)
class Depends:
dependency: Optional[Callable[..., Any]] = None
use_cache: bool = True
scope: Union[Literal["function", "request"], None] = None
ラッパー関数: param_functions.py:2221-2298
- ドキュメント付きの関数として定義され、内部で params.Depends を返す
エクスポート: init.py:14
from .param_functions import Depends as Depends
2. Depends の処理フロー
フェーズ1: ルート登録時（起動時）
@app.get("/items/")
↓
APIRouter.api_route() [routing.py:1047]
↓
APIRouter.add_api_route() [routing.py:965]
↓
APIRoute.__init__() [routing.py:510]
↓
get_dependant() [dependencies/utils.py:230]
↓
analyze_param() [dependencies/utils.py:342]
→ Depends を検出して依存性グラフを構築
フェーズ2: リクエスト処理時（実行時）
リクエスト受信
↓
get_request_handler() [routing.py:295]
↓
solve_dependencies() [dependencies/utils.py:565]
→ 依存性を再帰的に解決
→ キャッシュをチェック
→ 依存関数を実行（async/sync/generator対応）
↓
エンドポイント関数に値を注入
両モードが特定した処理フロー
検証③：変更の影響範囲の分析 — Planモードの方が網羅的
質問：
fastapi/routing.pyを変更した場合、影響を受けるファイルをリストアップして
結果比較
| 観点 | 通常モード | Planモード |
|---|---|---|
| コアファイル | 4 | 4 |
| テストファイル | 25 | 26 |
| ドキュメント/サンプル | 6 | 16 |
| 合計 | 35 | 46 |
| 影響度の評価 | なし | あり |
Planモードは以下のような追加ファイルも特定しました：
-
docs_src/bigger_applications/配下のルーター関連ファイル - Pythonバージョン別ファイル（
tutorial003_py39.pyなど）
検証④：複雑な仕組みの理解 — 通常モードが深く掘り下げた回答を出力
質問：
FastAPI全体のエラーハンドリングの仕組みを、関連する全ファイルを特定しながら網羅的に説明して
結果比較
| 観点 | 通常モード | Planモード |
|---|---|---|
| セクション数 | 12 | 6 |
| 特定したファイル数 | 約13 | 6 |
| コード例 | あり（複数） | なし |
| ファイル相関図 | あり | なし |
| テストファイル言及 | 4つ | なし |
通常モードが深く掘り下げた回答を出力：複雑な仕組みの説明では圧倒的です。
Planモードは「計画に必要な情報」をサマリー的にまとめる傾向にあります。
通常モードが生成したファイル相関図
┌─────────────────────────────────────────────┐
│ 1. ServerErrorMiddleware │
├─────────────────────────────────────────────┤
│ 2. User Middleware (カスタム) │
├─────────────────────────────────────────────┤
│ 3. ExceptionMiddleware │
├─────────────────────────────────────────────┤
│ 4. AsyncExitStackMiddleware │
├─────────────────────────────────────────────┤
│ 5. APIRouter (アプリケーションロジック) │
└─────────────────────────────────────────────┘
モード別の得手不得手
| モード | 得意なタスク | 苦手なタスク |
|---|---|---|
| 通常モード | 深い理解、詳細な説明、コード例生成 | - |
| Planモード | 影響範囲の網羅的リストアップ、表形式出力 | 複雑な仕組みの詳細説明 |
使い分けの指針
| やりたいこと | 推奨モード |
|---|---|
| 「〇〇をリストアップして」 | Planモード |
| 「〇〇を変更したら影響範囲は？」 | Planモード |
| 「〇〇の仕組みを詳しく説明して」 | 通常モード |
| 「〇〇のコード例を見せて」 | 通常モード |
まとめ
できること
- ディレクトリ構造の正確な把握
- 依存関係の追跡（行番号レベルで特定）
- 変更の影響範囲分析（数十ファイルを網羅的にリストアップ）
- 複雑な仕組みの体系的な説明
- アスキーアートによる図やコード例の生成
注意点
- エージェントへの委譲により、探索結果が毎回微妙に異なる
- Planモードは「計画不要」と判断すると自らモードを終了する
- タスクの性質に応じたモード選択が重要
FastAPIのような大規模OSSリポジトリに対して、Claude Codeは強みを示しました。
Claude Codeは、大規模なOSSリポジトリでも十分に実用的なレベルでコードを理解できることが分かりました。特に印象的だったのは、ソースコードの具体的な行番号まで特定できる精度の高さです。
また、通常モードとPlanモードには明確な得意分野の違いがあります。
- 「リストアップ」「影響範囲」 → Planモード
- 「仕組みの理解」「詳細な説明」 → 通常モード
今回の検証でPlanモードが影響範囲分析に強いことが分かりました。
タスクに応じた使い分けで、Claude Codeの能力を引き出していこうと思います。
最後までお付き合い頂き、ありがとうございました。
参考
DeltaXは、学習塾を探しているお子様やその保護者の方向けに「塾選び」をサポートする学習塾検索サイト『塾選』 を運営しています。 こちらでは技術的な内容をメインで取り扱います。 delta-x.co.jp/
Discussion