はじめに

code_search

こんにちは。
開発部でエンジニアをしている西尾です。
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モード
「〇〇の仕組みを詳しく説明して」	通常モード
「〇〇のコード例を見せて」	通常モード

まとめ

code

できること

ディレクトリ構造の正確な把握
依存関係の追跡（行番号レベルで特定）
変更の影響範囲分析（数十ファイルを網羅的にリストアップ）
複雑な仕組みの体系的な説明
アスキーアートによる図やコード例の生成

注意点

エージェントへの委譲により、探索結果が毎回微妙に異なる
Planモードは「計画不要」と判断すると自らモードを終了する
タスクの性質に応じたモード選択が重要

FastAPIのような大規模OSSリポジトリに対して、Claude Codeは強みを示しました。
Claude Codeは、大規模なOSSリポジトリでも十分に実用的なレベルでコードを理解できることが分かりました。特に印象的だったのは、ソースコードの具体的な行番号まで特定できる精度の高さです。

また、通常モードとPlanモードには明確な得意分野の違いがあります。

「リストアップ」「影響範囲」 → Planモード
「仕組みの理解」「詳細な説明」 → 通常モード

今回の検証でPlanモードが影響範囲分析に強いことが分かりました。
タスクに応じた使い分けで、Claude Codeの能力を引き出していこうと思います。
最後までお付き合い頂き、ありがとうございました。

参考

Discussion