未知の大規模コードベースに放り込まれて、どこから読めばいいか途方に暮れた経験は誰しもあるはずです。Claude Code は「このリポジトリの全体像を教えて」と聞くだけで構造を説明し、特定機能の実装箇所を探し、変更の影響範囲まで追ってくれます。本記事では、新メンバーのオンボーディングを Claude Code でどう加速するかを、2026年6月時点の公式仕様に沿って実例つきで解説します。
結論：Claude Code は「コードを読むパートナー」になる
大規模コードベースの理解を Claude Code に任せる、と聞くと「AI が勝手にコードを書くのでは」と身構える人がいます。が、ここで使うのは読む・説明する・案内する機能だけです。一行も変更せずに、コードベースの地図を描いてもらえます。
- 要点1：全体像は対話で掴む — 「このコードベースの概要を教えて」から始め、アーキテクチャ・データモデル・認証フローへと段階的に深掘りする。
- 要点2：実装箇所は自然言語で探す — 「ユーザー認証を扱うファイルはどれ？」と聞けば該当ファイルを特定し、「ログイン処理をフロントからDBまで追って」で呼び出し関係を辿る。
- 要点3：理解の成果は CLAUDE.md に残す — 読み解いた構造・ビルドコマンド・規約を
/initで下書きし、次に入る人とAI双方の地図にする。
対象読者：新しいプロジェクトに参画したエンジニア、レビュー担当のリードエンジニア、PM/テックリードとして引き継ぎ資料を整えたい人。今日できること：手元のリポジトリのルートで claude を起動し、まず「概要を教えて」と聞いてみる、それだけです。
ひとつだけ、最初に釘を刺しておきます。AI の説明は誤ることがあります。重要な理解（セキュリティに関わる箇所、お金が動くロジック、本番の挙動）は、Claude の説明を鵜呑みにせず必ず実コードで裏取りしてください。本記事でもその検証ステップを各所に挟みます。
① 全体像をつかむ — アーキテクチャ・主要ディレクトリ・データフロー
新しいリポジトリに入った初日、最初にやるべきは「広く浅く」全体像を掴むことです。いきなり個別ファイルを開くと、文脈なしのコードに溺れます。Claude Code 公式の「Understand new codebases」ワークフローも、広い質問から始めて段階的に絞り込むことを推奨しています。
まずプロジェクトルートに移動して Claude Code を起動し、高レベルの概要を尋ねます。
cd /path/to/project
claude起動したら、対話で順に深掘りしていきます。実際に使えるプロンプト例がこちらです（公式ドキュメントの例をベースにしています）。
# 1. まず全体像
このコードベースの概要を教えて
# 2. アーキテクチャパターンを掘る
ここで使われている主要なアーキテクチャパターンを説明して
# 3. データモデルを把握
主要なデータモデルは何？
# 4. 横断的な関心事を確認
認証はどう扱われている？ ロギングの仕組みは？このとき意識したいのは、そのプロジェクト固有の用語で質問することです。「ドメイン用語の用語集を作って」と頼むと、社内独自の略語やモジュール名が一気に整理されます。私が初見のリポジトリでまずやるのはこれで、用語集があるだけで以降の会話の精度が段違いになります。
主要ディレクトリの構造を知りたいときは、@ でディレクトリを参照すると、わざわざ Claude にファイルを読ませる前に一覧を渡せます。
@src/components のディレクトリ構成はどうなっている？ディレクトリ参照は中身ではなくファイル一覧を返すので、トークン消費を抑えつつ「どこに何があるか」を素早く把握できます。データフローを追いたいなら「リクエストがフロントエンドからデータベースに届くまでの流れを追って」のように、起点と終点を明示するのがコツです。
失敗しがちなポイント：いきなり深掘りしすぎる
❌ 初日から「この500行の関数を一行ずつ解説して」と頼む → 文脈がないまま細部に潜り、全体像が見えない。
⭕ 「概要 → アーキテクチャ → データモデル → 個別機能」の順に降りていく → 地図を持ってから細部に入るので迷子にならない。
② 特定機能の実装箇所を追う — 呼び出し関係と実行フロー
全体像が掴めたら、次は「あの機能、どこで実装されてるんだ？」という具体的な問いに移ります。grep を手で叩いて当たりをつける作業を、Claude Code は自然言語で肩代わりしてくれます。公式の「Find relevant code」ワークフローはこの3ステップです。
- 関連ファイルを特定する — 「ユーザー認証を扱っているファイルを見つけて」のように、探したい機能を自然言語で伝える。
- コンポーネントの連携を理解する — 「これらの認証ファイルはどう連携している？」で、ファイル同士の関係性を説明させる。
- 実行フローを追う — 「ログイン処理をフロントエンドからデータベースまで追って」で、呼び出しの連鎖を一気に可視化する。
うまく探させるコツは、具体的に・プロジェクトのドメイン言語で聞くことです。「認証」より「OAuthのトークンリフレッシュ」、「データ処理」より「在庫の日次集計バッチ」のほうが、Claude は正確に当たりをつけます。
呼び出し関係や参照を正確に辿りたい場合、公式はコードインテリジェンス・プラグインの導入を勧めています。これは言語サーバー（LSP）と Claude をつなぐもので、ファイルを総当たりでスキャンする代わりに「定義へジャンプ」「参照を検索」を正確に実行できます。TypeScript なら次のコマンドでインストールできます。
/plugin install typescript-lsp@claude-plugins-official公式マーケットプレイスには TypeScript・Python・Go・Rust など主要言語のプラグインが揃っています。大規模リポでシンボルの定義元・呼び出し元を辿る作業は、これがあるかないかでファイル読み込み回数（＝トークン消費）が桁違いに変わります。
ここでも実コードで裏取りを
「ログイン処理は AuthController 経由でDBに到達する」と Claude が説明したら、その AuthController を自分の目で開いて確認しましょう。AI の説明はもっともらしく聞こえても経路を取り違えていることがあります。特に「呼び出し関係」は、実際にはミドルウェアやフックを経由していて説明から漏れるケースがあります。プラグインの「参照を検索」を併用すると、この取り違えを大幅に減らせます。
③ 変更前に依存・副作用を把握する
コードを変える前に必ず聞きたいのが「ここを触ると、どこに影響する？」です。大規模コードベースほど、一見独立した関数が思わぬ場所から呼ばれています。新メンバーが最初にやらかすのは、たいていこの影響範囲の見落としです。
変更前の影響範囲調査は、メインの会話を汚さないためにサブエージェントに任せるのが公式推奨です。サブエージェントは独立したコンテキストウィンドウでファイルを読み、結果のサマリーだけを返してきます。
サブエージェントを使って、決済モジュールの calculateTax 関数が
どこから呼ばれているか、変更したときの影響範囲を調べて探索でメインのコンテキストを使い切ってしまう「無限探索」は、公式が挙げる典型的な失敗パターンのひとつです。サブエージェントに切り出せば、何十ファイルを読もうとメインの会話はクリーンなまま保てます。
さらに安全に進めたいならプランモードです。Claude がファイルを読んで変更計画を提示するだけで、承認するまでディスクには一切手を付けません。起動はこうです。
claude --permission-mode planセッション中なら Shift+Tab でプランモードに切り替えられます。「Google OAuth を追加したい。どのファイルを変更する必要がある？ セッションのフローは？ 計画を立てて」のように聞けば、影響を受けるファイルと手順が出てきます。実装に入る前にこの計画を Ctrl+G でエディタに開いて自分の理解と突き合わせる、これが新メンバーの事故防止に効きます。
失敗しがちなポイント：影響範囲を聞かずに変更する
❌ 「この関数のバグを直して」とだけ頼んで即実装させる → 同じ関数を使う別機能を壊す。
⭕ 「直す前に、この関数の呼び出し元と副作用を洗い出して。それからプランを出して」と一段挟む → 影響を見てから手を入れる。
④ オンボーディング資料を作る — CLAUDE.md と README の下書き
ここが、新メンバーのオンボーディングを「次の人」へ引き継ぐ要です。せっかく読み解いた構造を、自分の頭の中だけに留めるのはもったいない。CLAUDE.md に落とせば、次に入る人も Claude 自身も同じ地図を共有できます。
CLAUDE.md は Claude Code が毎セッション冒頭で読み込む、プロジェクトの永続的な指示書です。ゼロから書く必要はありません。/init コマンドを実行すると、Claude がコードベースを解析してビルドコマンド・テスト手順・規約を含む下書きを自動生成します。
/init既に CLAUDE.md がある場合、/init は上書きせず改善提案を出します。生成された下書きを、Claude が自力で気づけない情報（環境変数の癖、非自明な落とし穴）で補強していくのが正しい使い方です。何を書き、何を書かないかは公式の指針が明快です。
| ✅ 書くべきこと | ❌ 書かないこと |
|---|---|
| 推測できないビルド/テストコマンド | コードを読めば分かること |
| デフォルトと異なるコードスタイル規約 | 標準的な言語慣習 |
| リポジトリ作法（ブランチ名・PR規約） | 頻繁に変わる情報 |
| プロジェクト固有のアーキテクチャ判断 | ファイル単位の冗長な説明 |
| 開発環境の癖（必須の環境変数） | 「きれいに書け」等の自明な助言 |
公式は1ファイルあたり200行以内を目安にしています。長すぎると Claude が指示を読み飛ばすので、各行について「これを消したら Claude がミスするか？」を自問し、しないなら削るのが鉄則です。大規模モノレポなら、ルートに全体規約を置き、パッケージごとに packages/api/CLAUDE.md のようなディレクトリ別 CLAUDE.md を置くと、作業中のコードに関係する規約だけが読み込まれます。
README の下書きも同じ要領です。「このリポジトリの新規参画者向け README を、セットアップ手順・ディレクトリ構成・主要なデータフローを含めて下書きして」と頼めば、読み解いた内容がそのまま引き継ぎ資料の骨子になります。ただし生成された資料は必ず人がレビューしてからコミットしてください。AI が構造を一部誤解したまま文書化すると、それを信じた次の人がさらに誤解する連鎖が起きます。
⑤ 大規模リポでの効率化 — 必要な所だけ読ませるコンテキスト管理
Claude Code を大規模コードベースで使う上で、最大の制約はコンテキストウィンドウです。会話・読んだファイル・コマンド出力がすべて溜まり、埋まるほど性能が落ちます。公式ベストプラクティスのほとんどは、この一点から導かれています。新メンバーが「Claude が途中から的外れになった」と感じるのは、たいていコンテキストの詰まりが原因です。
大規模リポで効かせたい工夫を、優先度順に挙げます。
- 探索はサブエージェントに切り出す — ③で触れたとおり、多数のファイルを読む調査はサブエージェントへ。メインの会話にはサマリーだけ戻る。
- 無関係なタスク間で
/clearする — 別の問題に移るときはコンテキストをリセット。長い会話に無関係な情報を溜めない。 - 生成物・ベンダーコードの読み込みをブロックする —
permissions.denyにReadルールを足して、dist/やvendor/をコンテキストから締め出す。 - 始める場所を絞る — モノレポなら作業対象のパッケージ（例：
packages/api/）でclaudeを起動する。無関係なパッケージの CLAUDE.md が読み込まれない。
生成コードやベンダーSDKの締め出しは、.claude/settings.json にこう書きます。
{
"permissions": {
"deny": [
"Read(./**/dist/**)",
"Read(./**/build/**)",
"Read(./vendor/**)"
]
}
}Claude の検索はデフォルトで .gitignore を尊重するため、node_modules/ のような無視済みパスは元から検索結果に出ません。問題になるのはチェックインされた生成コードで、これは上記の deny ルールで明示的に閉じます。コードインテリジェンス・プラグイン（②で導入）と組み合わせると、「無関係なファイルをコンテキストに入れない」「残ったファイルも総当たりせず定義へジャンプ」の二段構えになり、トークン効率が大きく改善します。
長いセッションで会話が散らかってきたら、/clear でリセットするか、/compact <指示> で要点だけ残して圧縮します。公式は「同じ問題で2回以上訂正したら、コンテキストは失敗した試行で汚れている。/clear して、学んだことを反映したより具体的なプロンプトで仕切り直せ」と明言しています。クリーンなセッション＋良いプロンプトは、長く汚れたセッションにほぼ常に勝ちます。
新メンバーのオンボーディングに落とし込む実践フロー
ここまでの①〜⑤を、新メンバーが入った初週のフローとしてまとめます。私がチームに新しいエンジニアを迎えるとき、実際にこの順で進めてもらっています。
- 初日：対象リポのルートで
claudeを起動し、「概要を教えて」「主要なアーキテクチャパターンは？」「用語集を作って」で全体像を掴む（①）。 - 2〜3日目：担当する機能について「○○を扱うファイルはどれ？」「処理を端から端まで追って」で実装箇所と実行フローを把握（②）。コードインテリジェンス・プラグインを導入。
- 初週後半：最初の小さな変更に入る前に、サブエージェントで影響範囲を調査し、プランモードで計画を確認（③）。
- 初週の締め：読み解いた構造を
/initで CLAUDE.md に落とし、README 下書きを作って、リードのレビューを受ける（④）。 - 常時：タスクが変わるたび
/clear、調査はサブエージェント、無関係な生成コードは deny で締め出す（⑤）。
公式ベストプラクティスも「新しいコードベースのオンボーディングでは、シニアエンジニアに聞くのと同じ質問を Claude にぶつけよ」と述べています。「ロギングはどう動く？」「新しいAPIエンドポイントはどう作る？」「foo.rs の134行目の async move は何をしている？」——こうした質問を直接投げるだけで、立ち上がりが速くなり、他のエンジニアの負荷も減ります。
つまずきやすい点とその回避
最後に、新メンバーが Claude Code でコードベース理解を進めるときに陥りやすい罠を、公式の「Common failure patterns」に沿って3つ挙げます。
- 無限探索：スコープを切らずに「調べて」と頼み、何百ファイルも読ませてコンテキストを埋める。→ 調査は範囲を絞るか、サブエージェントに切り出す。
- 盛りすぎ CLAUDE.md：あれもこれも書いて長くなり、肝心のルールが埋もれて無視される。→ 「消したらミスするか？」で容赦なく刈り込む。
- 信用しっぱなし：もっともらしい説明をそのまま信じ、実コードで裏取りしない。→ セキュリティ・課金・本番挙動に関わる理解は必ず自分の目で確認する。
Claude Code は、未知の大規模コードベースを前にした新メンバーにとって「いつでも質問できるシニアエンジニア」になります。ただしその答えは出発点であって、終着点ではありません。地図を描いてもらい、自分の足で歩いて確かめる——この組み合わせが、オンボーディングを最速にする現実的な答えです。
次にやること
- 手元の一番大きいリポジトリで
claudeを起動し、「このコードベースの概要を教えて」と聞いてみる。 - 担当言語のコードインテリジェンス・プラグインを
/plugin installで導入する。 /initで CLAUDE.md の下書きを作り、チームでレビューして育てる。
チーム全体で Claude Code を使ったオンボーディングを定着させたい、あるいは大規模コードベースでの導入を伴走してほしい場合は、Uravation の Claude Code 個別指導・導入支援 でご相談ください。実際の現場リポジトリを題材に、読み解き方からCLAUDE.md設計までハンズオンで支援します。
大規模コードベースの理解は、設計思想を変える「移行・リファクタする側」とは別の技術です。改修側の進め方はClaude Codeでレガシーコード移行・大規模リファクタに、CLAUDE.md の設計を深掘りしたい人はCLAUDE.md設計・運用ガイドにまとめています。コンテキスト管理をさらに突き詰めるならClaude Codeのコスト最適化ガイド、全機能を学習順に押さえたい人はClaude Code 実践テクニック完全ガイドもあわせてどうぞ。
著者プロフィール
佐藤傑（さとう・すぐる）。株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援を手がける。著書『AIエージェント仕事術』（SBクリエイティブ）。
参考・出典
- Common workflows — Claude Code Docs（Understand new codebases / Find relevant code / Delegate research to subagents）
- How Claude remembers your project（CLAUDE.md / /init / memory hierarchy）— Claude Code Docs
- Set up Claude Code in a monorepo or large codebase — Claude Code Docs
- Best practices for Claude Code（context management / ask codebase questions）— Claude Code Docs
- Discover plugins（code intelligence）— Claude Code Docs
