他人が書いた巨大コードベースをClaude Codeで地図化する手順

引き継いだリポジトリをgit cloneして、開いた瞬間に固まったことがあります。トップ階層だけでフォルダが30個。READMEは1年半前で更新が止まっていて、書いてあるセットアップ手順はもう動かない。「ログイン処理どこ？」と検索したら、同じ単語が600件ヒットして画面が真っ黒になりました。

このとき僕がやってしまったのは、Claude Codeに「このプロジェクト全部読んで、リファクタの提案して」と丸投げすることでした。返ってきたのは、読んでもいないファイルへの自信たっぷりの感想と、触ったら一発で本番が落ちる場所への軽い変更提案。賢いはずなのに、まるで土地勘がない。

理由はシンプルで、他人が書いた大規模コードは「賢さ」では攻略できないからです。必要なのは土地勘で、土地勘は地図から生まれます。今日は、いきなりコードを直す前に、リポジトリの全体像を1枚の地図に落とす手順を書きます。実装ではなく「掴み方」の話です。

この記事の要点

• 大規模・他人のコードは、最初の成果物を「差分」ではなく「地図」にする。地図がない状態で直すと、読んでいない場所を壊す。
• 地図は4層で作る。①入口（どこから動くか）②主要ディレクトリ③依存関係（誰が誰を呼ぶか）④危険領域（壊すと事業が止まる場所）。
• Claude Codeには「まだ編集しない・推測で断定しない・未確認は未確認と書く」を最初に固定する。これだけで暴走が止まる。
• 具体的な初回プロンプトは既存コードを読む最初のプロンプト7選、巨大リポジトリの検索術は巨大コードベースを読む検索術に分けてある。この記事は全体像の掴み方に集中する。
• 掴んだ要点は会話に流したままにせず、CLAUDE.mdに短く残す。次のセッションが調査ゼロから始まる。

なぜ「賢いAI」が他人のコードで迷子になるのか

Claude Codeは、公式のOverviewでも「コードベースを読み、ファイルを編集し、コマンドを実行する」ツールだと説明されています。読む力はある。問題は、最初に何を読ませるかを人間が決めていないことです。

新しく入った会社で、誰かに「このビル、自由に見て回っていいよ」と言われた場面を想像してください。地図も組織図もないまま歩き回ったら、どこが受付でどこがサーバー室か分からない。下手したら配電盤を開けてしまう。AIも同じで、地図なしに「全部見て」と言われると、目についた順に読み、目についた場所をいじろうとします。

しかも大規模リポジトリには、読む価値の薄いものが大量に混ざっています。node_modules、dist、.next、自動生成のスナップショット。ここを読ませると、地図が分厚いだけで使えなくなる。「全部読む」は不可能だし、不要です。プロが新しいコードを掴むときも、全部は読みません。入口から、必要な道だけを辿ります。

全体像は4つの層で掴む

僕が他人のコードを地図化するときは、いつもこの4層を上から順に埋めます。順番が大事で、入口を先に押さえないと依存も危険領域も読み違えます。

層	掴むこと	具体例	なぜ先に要るか
1. 入口	どこから処理が始まるか	main、サーバー起動、ルーティング、CLIコマンド、ジョブ定義	ここを起点に「動く道」だけ辿れる
2. 主要ディレクトリ	大きな部屋の役割	src/api、src/web、packages/core、infra	全部読まず、どの部屋に何があるか地図化
3. 依存関係	誰が誰を呼ぶか	coreは誰からも呼ばれる、apiはcoreに依存	変更の波及範囲を読む。下層ほど触ると怖い
4. 危険領域	壊すと事業が止まる場所	認証、決済、削除、本番設定、秘密情報、デプロイ	「今日は触らない」を明文化する

入口さえ見つかれば、あとはそこから糸をたぐるように読めます。逆にいうと、入口が分からないまま個別ファイルを読むのは、本のページを真ん中から1枚ずつ眺めるようなものです。話がまったく入ってきません。

ステップ1: 読み取り専用で外形を撮る

最初はClaude Codeに編集させず、僕も書き換えません。まずリポジトリの外形を機械的に撮ります。Windowsならそのまま使えます。

git status --short
git log --oneline -10
Get-ChildItem -Force | Select-Object Name, Mode
Get-ChildItem -Recurse -File -Include package.json,*.config.*,README*,CLAUDE.md,AGENTS.md,Dockerfile,docker-compose.* | Select-Object -ExpandProperty FullName

ここで見るのは4つです。技術スタック（package.jsonや設定ファイル）、ドキュメントの有無、コンテナ定義の場所、そして未コミット差分。最後の未コミット差分は、他人のコードでは特に大事です。前任者の作業途中が残っていることがあり、それを知らずにAIに任せると、他人の変更を自分の成果として上書きしてしまいます。

外形を撮ったら、Claude Codeへの最初の指示はあえて「読むだけ」に縛ります。具体的なプロンプト集は最初のプロンプト7選に分けてあるので、ここでは縛り方の骨だけ示します。

このリポジトリを既存コードベースとして読みます。まだ編集しないでください。

目的: 全体像を地図にする。実装はしない。

出してほしいもの:
1. 技術スタックの要約（言語・フレームワーク・主要ライブラリ）
2. 実行入口を最大5つ（ファイルパスつき）
3. 主要ディレクトリを最大8つと、それぞれの役割を1行で
4. 危険領域と、その理由
5. 自動生成・キャッシュとして読まなくてよい場所

ルール:
- 推測で断定しない。確認できないものは「未確認」と書く
- node_modules・dist・ビルド生成物は地図に入れない

「まだ編集しないでください」と「未確認と書いて」は、毎回必ず入れます。Claude Codeは親切なので、読んでいる途中で「ついでに直せます」と前に出たがる。でも他人の大規模コードでは、地図の質がその後の差分の質を決めます。ここで急ぐと、あとで全部やり直しになります。

ステップ2: 入口から依存をたぐる

入口リストが出たら、次は「その入口から何が呼ばれているか」を辿ります。全ファイルを読むのではなく、入口を起点にした1本道を作るイメージです。Claude Codeにはこう頼みます。

さきほどの入口のうち、Webサーバーの起動ファイルから読み解いてください。
このファイルが最初に呼ぶモジュールを順にたどり、
「リクエストが来てからレスポンスを返すまで」の主要な通り道を、
ファイルパスつきの箇条書きで示してください。脇道は省略してOKです。

こうすると、600件ヒットしていた検索結果が、十数個の「実際に通る道」に絞られます。僕はこれを処理の通り道と呼んでいます。ログイン処理を探すなら、「ログインのリクエストがどのファイルを通って、どこでDBに当たるか」を1本だけ出させる。これで「で、ログイン処理どこ？」の独り言が消えます。

依存の方向も必ず聞きます。「このモジュールは誰から呼ばれていて、誰を呼んでいるか」。下層（多くから呼ばれる共通部品）ほど、変更すると波及が広く、触るのが怖い場所です。逆に末端の画面1つは、壊しても影響が狭い。この上下関係が、最初に直す場所を選ぶ基準になります。検索の段階的な絞り方そのものは巨大コードベースを読む検索術に詳しく書いたので、深掘りはそちらへ。

ステップ3: 危険領域に権限で柵を立てる

口で「触らないで」と言うだけでは柵になりません。他人のコードでは、どこが危ないか自分もまだ完全には分かっていない。だから、確実に危ない種類の操作は権限で止めます。公式のpermissionsドキュメントにあるとおり、allow・ask・denyでツール利用を制御できます。

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Read"
    ],
    "ask": [
      "Bash(npm run build *)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(.env)",
      "Read(**/.env)",
      "Edit(**)"
    ]
  }
}

地図を作っている段階では、Editをまるごとdenyに入れてしまうのが僕の好みです。読むだけと決めたセッションで、うっかり編集が走らない。地図が固まって、最初に直す1ファイルが決まってから、その範囲だけaskに格上げします。許可を増やすより先に、何を禁止するかを決める。これが他人のコードで事故らない順番です。権限の細かい設計はClaude Code権限設定ガイドにまとめてあります。

ステップ4: 掴んだ全体像をCLAUDE.mdに残す

ここが一番もったいないポイントです。せっかく地図を作っても、チャットに流したままだと、翌日の別セッションでまた600件の検索からやり直しになります。

Claude Codeは、公式のmemoryドキュメントにあるとおり、CLAUDE.mdをセッション開始時に毎回読み込みます。つまりここに全体像の要点を置けば、次回は地図を持った状態で会話が始まる。ただし、初回調査の生データを全部貼ると重くなるので、安定した要点だけを短く残します。

# CLAUDE.md（抜粋: このリポジトリの地図）

## 入口
- Webサーバー起動: src/server/main.ts
- APIルーティング: src/api/router.ts
- バッチ: src/jobs/cron.ts

## 主要ディレクトリ
- src/core … 共通ロジック（多くから呼ばれる。変更は慎重に）
- src/api … HTTPハンドラ。core に依存
- src/web … 画面。末端なので影響範囲は狭め
- infra … デプロイ・環境設定（基本さわらない）

## 触らない領域（理由つき）
- 認証 src/core/auth … 全機能に波及
- 決済 src/api/billing … 売上に直結
- .env と secrets … 漏洩・本番停止リスク

## 検証コマンド
- ビルド: npm run build
- テスト: npm run test

## 次に確認したい未確認事項
- 本番デプロイは手動か自動か
- メール送信はどのサービス経由か
- 価格の正データはどのファイルか

末尾の「未確認事項」を3つだけ残しておくのが、地味に効きます。次のセッションでこの3問から始めるだけで、会話がいきなり深いところからスタートします。CLAUDE.mdの書き方の型はCLAUDE.mdスターターテンプレートにあります。

コピペで使える: 地図の最低限チェック

地図は人間が読むメモですが、必要な項目が抜けていないかは機械で見られます。次のスクリプトは、CLAUDE.mdに地図として必須の見出しが揃っているかだけを確認します。check-map.mjsとして保存し、node check-map.mjs CLAUDE.mdで実行できます。

import { readFileSync } from "node:fs";

// 対象ファイル（既定は CLAUDE.md）
const file = process.argv[2] || "CLAUDE.md";
const text = readFileSync(file, "utf8");

// 地図として最低限ほしい見出し
const required = ["入口", "主要ディレクトリ", "触らない領域", "検証コマンド", "未確認"];
const missing = required.filter((heading) => !text.includes(heading));

if (missing.length > 0) {
  console.error(`地図に足りない項目: ${missing.join(", ")}`);
  process.exit(1); // CIで落とせるように非ゼロ終了
}

console.log(`OK: ${file} に地図の最低項目がそろっています。`);

node check-map.mjs CLAUDE.md

高度な品質チェックではありません。それでも「入口を書き忘れた地図」「危険領域が空欄の地図」を弾くだけで、他人のコードを引き継ぐたびに同じ抜けを繰り返さなくなります。Claude Codeに「最後にこのスクリプトが通る形で地図を更新して」と頼めば、会話の終わりに残るメモの質が安定します。

僕がやらかした失敗3つ

正直に書きます。他人のコードの地図化は、最初ぜんぶ失敗しました。

ひとつ目は、入口を確認する前に個別ファイルを読み始めたこと。気になったファイル名から開いていったら、それが実は使われていない古いコードで、半日溶かしました。今は必ず入口リストを先に作り、「この道は本当に通るのか」をAIに確認させてから読みます。

ふたつ目は、生成物まで地図に入れたこと。rg --filesの結果をそのままClaude Codeに渡したら、dist配下の何千ファイルを真面目に分類し始めて、地図が分厚いだけのゴミになりました。読まなくていい場所を先に除外指示する。これだけで地図が一気に使えるものになります。

みっつ目は、地図を会話に残したまま閉じたこと。翌日「昨日のあれ」と聞いても、新しいセッションのAIは何も覚えていない。当たり前なんですが、忙しいと忘れます。CLAUDE.mdに要点を移すクセをつけてから、引き継ぎの調査時間が体感で半分以下になりました。

よくある質問

Q. 大規模リポジトリは、結局どれくらい読めばいいですか？ A. 全部読む必要はありません。入口から「実際に通る道」を1本ずつ辿り、変更したい機能の周辺だけ深く読みます。プロも全部は読まず、必要な道だけたどります。

Q. READMEが古くて動きません。何から信じればいいですか？ A. ドキュメントよりコードと実行入口を信じます。package.jsonのscripts、起動ファイル、CI設定（.github/workflowsなど）は、実際に動いている事実なので古い説明より正確です。

Q. 地図づくりとコードを直す作業は、同じセッションでいいですか？ A. 分けるのをおすすめします。地図づくりのセッションはEditを禁止にして読むだけに徹し、地図が固まってから別セッションで1ファイルだけ直す。境界を分けると暴走が起きません。

Q. この記事と姉妹記事はどう使い分けますか？ A. この記事は「全体像の掴み方（地図化）」、最初のプロンプト7選は「最初に投げる具体的な指示文」、巨大コードベースを読む検索術は「rgでの絞り込みと依存追跡」です。地図→プロンプト→検索の順で読むとつながります。

Q. 一人で開発するときも地図は要りますか？ A. 3か月後の自分は他人です。久しぶりに開いたリポジトリは他人のコードと変わらないので、CLAUDE.mdの地図は自分のためにも効きます。

まとめ

他人が書いた巨大コードベースをClaude Codeで攻略するコツは、賢いプロンプトを探すことではありません。最初に地図を作ることです。入口・主要ディレクトリ・依存関係・危険領域の4層を、読み取り専用で機械的に埋める。出てきた要点をCLAUDE.mdに短く残し、次のセッションが土地勘を持った状態で始まるようにする。

実際に試した結果、僕の手元では、いきなり「直して」と頼んだセッションより、先に地図を作ったセッションのほうが、最初の差分にたどり着くまでが圧倒的に速くなりました。特に大規模リポジトリでは、入口と依存の上下関係を先に押さえておくと、「どこから直すと安全か」を毎回ゼロから悩まなくて済みます。次に他人のコードを引き継いだら、まず1枚の地図から始めてみてください。

このやり方をチームの仕組みに落とし込みたいときは教材・テンプレート一覧、権限設計や運用まで相談したいときはClaude Code研修・導入相談がそのまま使えます。