Claude Codeで大規模コードベースを探索するコツ

初めて触るコードベースでいきなり「このリポジトリを全部読んで説明して」と頼むと、返ってくる答えも漠然としたものになりかねません。効くのは、全体像→アーキテクチャの要所→実行フローの追跡という3段階で質問を絞り込む進め方です。公式のプロンプト例も、広い質問から狭い質問へ並んでいます。

3段階に分けると回答の解像度が上がる理由

Claude Codeは、聞かれた内容に応じて読みにいくファイルを決めます。最初から「認証まわりのバグを直したい」と狭く聞くと、設計の前提を共有しないまま局所の修正に入ることになります。逆に「概要を教えて」で止めると、次に何を聞けばいいか分からず会話が途切れます。

そこで、広い質問から始めて徐々に狭めます。主要な設計判断から順に、全体像、機能単位の掘り下げ、実行フローの追跡と聞いていきます。

第1段階: 全体像を広い質問で確認する

最初の質問はプロジェクトルートで実行し、構造そのものを聞きます。ディレクトリ構成やモジュール分割の意図は、ここで押さえます。

このコードベースの概要を教えて

続けて、アーキテクチャパターン・データモデル・認証方式のように、設計判断が集中する領域を聞きます。質問は1つずつ分けて投げます。

ここで使われている主要なアーキテクチャパターンを説明して
主要なデータモデルは何ですか
認証はどう処理されていますか

この段階では、プロジェクト固有の用語集を作らせる使い方も公式が挙げています。「このプロジェクトでよく出てくる独自用語を一覧にして」と頼めば、略語や社内呼称をまとめて説明させられます。コーディング規約や命名のルールを聞くのも、この段階です。

第2段階: アーキテクチャの要所を掘り下げる

全体像がつかめたら、機能単位で関連コードを横断的に探させます。ファイル名を知らなくても、機能名や振る舞いから逆引きできるのがこの段階の狙いです。

ユーザー認証を扱うファイルを見つけて
これらの認証関連ファイルはどう連携していますか

「関連するファイルを見つけて」で終わらせず、続けて「それらがどう連携しているか」まで聞きます。ファイルの一覧だけでは呼び出し順序や責務の分担が分からないためです。

質問には、プロジェクトで実際に使われているドメイン用語を混ぜます。公式の手順にも、プロジェクトのドメイン用語を使うことが挙がっています。決済まわりを探るなら、そのプロジェクトが「課金」と呼んでいる語をそのまま使う、という具合です。

第3段階: 入り口から出口まで実行フローを追う

最後は、入り口から出口までの実行フローを1本の線として追わせます。ログイン処理のように、フロントエンドからデータベースまで複数レイヤーをまたぐ処理で効きます。

ログイン処理をフロントエンドからデータベースまで追跡して

この質問は読むファイルが多くなりやすいので、第1・第2段階で構造を共有してから投げます。

3段階を崩しがちな聞き方

3段階を意識していても、聞き方次第で効果は薄れます。崩れやすい型は3つあります。

第1段階を飛ばして実装を頼む。「このバグを直して」から始めると、原因が別モジュールの設計にある場合に、その設計を知らないまま修正に入ることになります。

第2段階で連携を聞かずに編集へ進む。「〇〇の処理をしているファイルはどこ」でファイルを受け取り、そのまま編集を頼むと、呼び出し元との連携を踏まえない修正になります。ファイルを特定したら、編集の前に連携を確認する一言を挟みます。

1つの質問に観点を詰め込む。「概要とアーキテクチャと認証の仕組みを全部教えて」のように詰め込まず、観点ごとに分けて聞きます。

サブエージェントと@参照でコンテキストを圧迫しない

調査は必要でも、読んだファイルをメインの会話に残したくない場面があります。そのときはサブエージェントに調査だけを委任します。サブエージェントは自分のコンテキストウィンドウでファイルを読み、結果の要約をメインセッションへ返します。

サブエージェントを使って、認証システムがトークンのリフレッシュをどう扱っているか調査して

向いているのは、メインの会話を実装用に空けておきたいときや、調査対象が広くファイル読み込みだけでコンテキストが埋まりそうなときです。サブエージェントは独自にリクエストを送るので、メインと同じ利用上限に数えられます。コンテキストは節約できても、使用量が減るわけではありません。委任の設計や独自エージェントの定義方法はClaude Code Sub-agents完全ガイドにあります。

対象ファイルがすでに分かっているなら、探索の質問を挟まず@参照で直接渡す手もあります。@src/utils/auth.jsのようにファイルを指定すると全文が会話に読み込まれ、@src/componentsのようにディレクトリを指定するとファイル一覧が渡されます。@を入力するとパス候補のメニューが開き、EnterかTabで選んだパスを入力できます。MCPサーバーに接続していれば、@github:repos/owner/repo/issuesのようにMCPリソースも同じ書式で参照できます。

起動する場所で、最初に見える範囲が決まる

質問の型とは別に、claudeをどのディレクトリで起動するかが、読み書きできるファイルと起動時に読み込まれるCLAUDE.mdを決めます。パッケージ数の多いモノレポや、数百万行の単一ツリーでは、この選び方が3段階の前提になります。

サブディレクトリから起動して隣のパッケージも読ませたいときは、--add-dirで追加します。v2.1.289のclaude --helpには、次のように出ます。

  --add-dir <directories...>            Additional directories to allow tool
                                        access to
  -w, --worktree [name]                 Create a new git worktree for this
                                        session (optionally specify a name)

追加の経路で、読み込まれるものが変わります。設定ファイルのpermissions.additionalDirectoriesは、ファイルへのアクセスだけを広げます。そのディレクトリのCLAUDE.mdもスキルも読み込まれません。--add-dirや/add-dirで追加すると、スキルは読み込まれ、CLAUDE.mdと.claude/rules/は環境変数CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1を付けたときだけ読み込まれます。

起動後にどのCLAUDE.mdが効いているかは、/contextのMemory filesの一覧で確かめられます。探索を始める前に一度見ておくと、読ませたつもりの規約が入っていない、という食い違いに気づけます。

探索のノイズを減らす: 読ませない範囲と言語サーバー

大きなリポジトリでは、ビルド成果物やベンダーコードを読ませない設定を入れられます。

検索は既定で.gitignoreに従うため、node_modules/やdist/、build/のように無視済みのパスは、検索結果に出ません。問題になるのは、リポジトリにコミット済みのベンダーSDKや生成コードです。こうしたパスは、permissions.denyのReadルールで開かせないようにできます。

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)",
      "Read(./**/*.generated.*)",
      "Read(./**/vendor/**/*)"
    ]
  }
}

このルールをリポジトリの全員に効かせるなら.claude/settings.jsonにコミットし、自分だけなら.claude/settings.local.jsonに書きます。ルートのsettings.local.jsonは、どこから起動しても読まれます。ただしWindowsなど、Claude Codeがリポジトリルートを使わない環境は例外です。サブディレクトリから起動する場合、そこに書く相対パターンは起動ディレクトリ基準になるため、//で始まる絶対パスで書きます。全セッションで強制したいときは、ユーザー設定やプロジェクト設定では上書きされない管理設定に置きます。ルートで起動するならルートの、サブディレクトリで起動するなら各パッケージの.claude/settings.jsonが読まれ、親ディレクトリからは引き継がれません。

パターンを/**/*で終えているので、ディレクトリの中身だけが対象になり、ls distやcd buildは通ります。拒否ルールが効くのは、組み込みのファイルツールと、Bashの中でcat・head・grep・findのようにClaude Codeが認識するファイルコマンドに拒否対象のパスが引数で渡された場合です。組み込みのGrepとGlobも、拒否したパスを結果から外す処理を試みます。ただし、Bashでgrep -rやfindを拒否対象を含むディレクトリに対して回すと、その出力には拒否したファイルも含まれます。サブプロセスが自分でファイルを開く場合も、対象外です。

定義や呼び出し元を探す質問には、言語サーバーに接続するコードインテリジェンスのプラグインが使えます。シンボルの定義へ飛んだり参照を探したりを、ツリーの走査ではなく言語サーバー経由でできます。TypeScriptなら、claudeを起動したうえで次を入力します。

/plugin install typescript-lsp@claude-plugins-official

Marketplace "claude-plugins-official" not foundと出たら、/plugin marketplace add anthropics/claude-plugins-officialでマーケットプレイスを追加してから、もう一度入れます。プラグインとは別に、その言語のサーバー本体のバイナリが各開発者のマシンに要ります。

--worktreeでセッションを新しいワークツリーで始めるときや、サブエージェントをワークツリーで隔離して並列に走らせるときは、worktree.sparsePathsにチェックアウトするディレクトリを列挙できます。Claudeがワークツリーを作る場面で、必要な部分だけが展開されます。ルート直下のファイルは常にチェックアウトされ、ルート直下のディレクトリは列挙したものだけです。ルートの.claude/を使いたければ、.claudeも列挙します。ワークツリーの中ではセッションの作業ディレクトリがワークツリーのルートになり、サブディレクトリの.claude/settings.jsonは読まれません。denyルールは、リポジトリルートの.claude/settings.jsonにも同じものが要ります。

ここから先、パッケージごとに読ませるCLAUDE.mdを分ける設計や、不要なCLAUDE.mdをclaudeMdExcludesで外す設定は、Claude Codeのコンテキスト管理が扱っています。パッケージ単位で権限や規約を分けるモノレポ特有の設計はClaude Codeモノレポ設計にあります。本稿の3段階は、そうした設定を済ませたあとに、対話でどう掘るかの話です。

状況別に効く質問パターンの早見表

質問の型は、状況によって向き不向きがあります。

プロジェクトの文脈が薄いほど広い質問から入り、厚いほどピンポイントで済みます。一度全体像をつかんだプロジェクトに戻ってきたときは、第1段階からやり直す必要はなく、対象が決まった修正なら第3段階や@参照から始められます。