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

初めて触るコードベースでいきなり「このリポジトリを全部読んで説明して」と頼むと、返ってくる答えは総花的になりがちです。効くのは、全体像→アーキテクチャの要所→具体的なファイルという3段階で質問を絞り込む進め方です。段階を踏むごとにClaude Codeが読みにいくファイルの範囲が狭まり、回答の解像度が上がります。

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

Claude Codeは聞かれた質問の粒度に合わせて読むファイルの範囲を決めます。最初から「認証まわりのバグを直したい」のような狭い質問をぶつけると、コードベース全体の文脈を持たないまま局所的な答えを返してしまい、的外れな修正につながることがあります。

逆に「概要を教えて」で止めてしまうと、次に何を聞けばいいか分からず会話が続きません。広い質問から始めて徐々に狭めるのが、公式のプロンプト例でも一貫している型です。以下の3段階を順に踏むと、初日でも主要な設計判断まで到達できます。

• 第1段階: プロジェクト全体の構造を聞く
• 第2段階: アーキテクチャの要所を掘り下げる
• 第3段階: 目的のファイルを特定して実行フローを追う

順序を変えても動きはしますが、段階を飛ばすとClaude Codeが参照するファイルが偏り、後の質問で同じ説明を聞き直す手戻りが増えます。特に第1段階を省いて個別のバグ修正から入ると、周辺の設計判断を知らないまま局所的な変更を積み重ねることになり、あとから整合性の取れない実装が見つかることがあります。数分の遠回りが、結果として調査のやり直しを防ぎます。

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

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

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

続けて、主要なアーキテクチャパターン・データモデル・認証方式のように、設計判断が集中する領域を個別に聞きます。ここで一度に全部を聞くより、1つずつ質問を分けたほうが回答が長くならず読みやすくなります。

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

この段階の質問は、プロジェクト固有の用語集を作らせるといった応用も効きます。「このプロジェクトでよく出てくる独自用語を一覧にして」のように聞くと、略語や社内呼称をまとめて説明させられます。

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

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

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

ポイントは「関連するファイルを見つけて」で終わらせず、続けて「それらがどう協調しているか」まで聞くことです。ファイルの一覧だけでは呼び出し順序や責務の分担が分からず、結局コードを自分で読み直す羽目になります。

質問には具体的なドメイン用語を混ぜます。「認証」「決済」のようにプロジェクトで実際に使われている語を使うと、Claude Codeがgrepやコード内検索で拾える手がかりが増え、回答の精度が上がります。

第3段階: 目的のファイルを特定して実行フローを追う

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

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

この質問はコードリーディングの負荷が高く、Claude Code側が読むファイル数も増えます。第1・第2段階を飛ばしてここから始めると、Claude Codeは文脈を持たないまま探索するため、途中で関係のないファイルまで開いてしまうことがあります。3段階を順に踏んでおくと、この最終段階で読むファイルが的確に絞られます。

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

同じ3段階を意識していても、聞き方を間違えると効果が薄れます。よくある崩れ方は次の3つです。

第1段階を飛ばしていきなり実装を頼む。「このバグを直して」から始めると、Claude Codeはバグの周辺だけを読んで修正案を出します。バグの原因が別モジュールの設計に起因している場合、この聞き方では気づけません。まず全体像を聞いてから修正に入ると、遠回りに見えて手戻りが減ります。

第2段階を丸ごとスキップして第3段階だけ聞く。「〇〇の処理をしているファイルはどこ」だけを聞いてファイルを受け取り、そのまま編集を頼むと、そのファイルが呼び出し元とどう連携しているかを踏まえない修正になりがちです。ファイルを特定したら、編集を頼む前に一度連携を確認する一言を挟みます。

質問を1文に詰め込みすぎる。「概要とアーキテクチャと認証の仕組みを全部教えて」のように複数の観点を1つの質問に混ぜると、回答が箇条書きの羅列になり、どこを深掘りすべきかが見えにくくなります。観点ごとに質問を分けたほうが、回答も次の質問も組み立てやすくなります。

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

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

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

メインの会話は実装用に空けておきたいとき、あるいは調査対象が広くファイル読み込みだけでコンテキストを圧迫しそうなときに向いています。委任の設計や独自エージェントの定義方法はClaude Code Sub-agents完全ガイドにまとめています。

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

モノレポや数百万行規模ではプロンプトだけで足りない

ここまでの3段階は、どのサイズのリポジトリでも通用する質問の型です。ただし数百万行規模の単一ツリーや、パッケージ数が多いモノレポでは、質問の工夫だけでは起動時点のコンテキストが埋まってしまいます。ネストしたCLAUDE.mdでパッケージごとに読ませる範囲を絞る、除外設定でノイズになるディレクトリを最初から見せない、といった設定側の対処が必要になります。この切り分けはClaude Codeのコンテキスト管理で扱っています。

パッケージ単位で権限や規約を分けたいモノレポ特有の設計判断はClaude Codeモノレポ設計に譲ります。本稿の3段階の質問は、そうした設定を済ませたあとの「対話でどう掘るか」の部分に当たります。

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

質問の型は状況によって向き不向きがあります。迷ったときの目安は次の通りです。

新規参加直後は上から順にたどり、対象がはっきりしている修正作業では表の下側から使う、という使い分けだと迷いが減ります。どのパターンを選ぶかは、自分がそのコードベースの文脈をどれだけ持っているかで決まると考えると判断しやすくなります。文脈が薄いほど広い質問から入り、文脈が厚いほどピンポイントの質問で済む、という関係だと捉えておくと表を見返す手間も減ります。

よくある質問

毎回3段階すべてを踏む必要がありますか

いいえ。対象ファイルが分かっている修正作業なら第3段階や@参照から始めて構いません。3段階が効くのは、プロジェクトの文脈をまだ持っていない場面です。すでに一度全体像を把握したプロジェクトへ戻ってきたときも、第1段階からやり直す必要はありません。

サブエージェントに調査を任せると精度は落ちませんか

サブエージェントは自分のコンテキストウィンドウでファイルを読むため、調査の精度自体はメインセッションで聞くのと変わりません。変わるのは、読んだファイルの中身がメインの会話に残らない点です。

モノレポでも同じ3段階で通用しますか

通用しますが、起動場所によって「全体像」の範囲が変わります。モノレポのルートで聞けばリポジトリ全体、特定パッケージのディレクトリで聞けばそのパッケージ内に絞られます。パッケージをまたぐ調査をしたいときは、ルートから起動してから第1段階の質問を投げます。

プロジェクト固有の用語が多くてついていけません

第1段階のタイミングで用語集を作らせるのが早道です。「このプロジェクトでよく出てくる独自用語を一覧にして」のように聞くと、略語や社内呼称をまとめて説明させられます。

コーディング規約も同じ流れで確認できますか

できます。第1段階の質問に「コーディング規約や命名のルールも教えて」を加えるか、別ターンで単独に聞きます。既存コードのパターンから規約を推測して答えてくれるため、明文化されたドキュメントが無いプロジェクトでも当たりをつけられます。