Claude Codeで既存コードベース地図を作る: 編集前45分の安全手順

既存コードベースでClaude Codeを使うとき、最初の成果物はコード差分ではありません。まず作るべきものは「このリポジトリはどこから動き、どこが危なく、どのコマンドで確かめるのか」を1枚にまとめた地図です。ここを飛ばして「全部読んで直して」と頼むと、Claude Codeは親切に広い範囲を調べ、ついでのリファクタや関係ない文言変更まで混ぜやすくなります。

この記事では、初心者でも45分で使えるrepo-mapの作り方を解説します。repo-mapとは、リポジトリの入口、主要ディレクトリ、触ってよい領域、触らない領域、検証コマンド、引き継ぎメモを短くまとめた作業用の地図です。公式のClaude Code overviewでも、Claude Codeはコードベースを読み、ファイルを編集し、コマンドを実行できる開発ツールとして説明されています。だからこそ、編集前に「何を読ませ、何を止めるか」を決める価値があります。

関連して、初回プロンプトは既存コードを読む最初のプロンプト7選、権限の考え方はClaude Code権限設定ガイド、チームに残す指示はCLAUDE.mdスターターテンプレートも合わせて読むとつながります。

45分で作るrepo-mapの全体像

45分の配分は、調査25分、地図化10分、最初の安全な作業選び5分、レビュー5分です。重要なのは、最初から完璧に理解しようとしないことです。既存コードの全体像は、地図を作ったあとに小さく直しながら深くなります。

flowchart TD
  A["読み取り専用で現状確認"] --> B["入口と主要ディレクトリを抽出"]
  B --> C["危険領域と安全領域を分ける"]
  C --> D["1つだけ安全な初回タスクを選ぶ"]
  D --> E["検証コマンドと手動確認を固定"]
  E --> F["repo-map.mdとして残す"]

初心者向けに用語を整理しておきます。入口とは、アプリが動き始めるファイルです。Webならルーティング、APIならサーバー起動やハンドラ、バッチならCLIコマンドが入口になります。危険領域とは、認証、決済、削除処理、本番設定、秘密情報、デプロイ、広告タグのように、軽い変更でも信用や売上に影響する場所です。検証コマンドとは、作業後に「壊していない」と言うための証拠を出すコマンドです。

ステップ1: 読み取り専用で棚卸しする

最初はClaude Codeに編集させず、人間もファイルを書き換えません。まずPowerShellでリポジトリの外形を見ます。Windows環境なら次のコマンドをそのまま使えます。

git status --short
Get-ChildItem -Force | Select-Object Name, Mode, Length
Get-ChildItem -Recurse -File -Include package.json,astro.config.*,next.config.*,vite.config.*,README*,CLAUDE.md,AGENTS.md | Select-Object -ExpandProperty FullName
rg --files | Select-Object -First 120

ここで見るのは、技術スタック、ドキュメントの有無、生成物やキャッシュの場所、未コミット差分です。未コミット差分がある場合は、まず誰の変更かを確認します。AIに任せる前に作業中の差分を知っておかないと、他人の変更を上書きしたり、関係ない修正まで自分の成果物として扱ったりします。

Claude Codeへ最初に渡すプロンプトは、次のように制限を強くします。

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

目的:
- 45分で最初のrepo-mapを作る
- 安全な初回タスクを1つだけ選ぶ
- 触ってはいけない領域を明確にする

出力:
1. 主要ディレクトリを最大8つ
2. 実行入口を最大5つ
3. 危険領域と理由
4. 安全そうな初回タスク候補を3つ
5. 検証コマンド候補

不明な点は推測で断定せず「未確認」と書いてください。

「まだ編集しないでください」は必ず入れます。Claude Codeは便利なので、読んでいる途中で「ついでに直せそうです」と進みたくなります。しかし既存コードの初回は、地図の質が差分の質を決めます。

ステップ2: repo-map.mdを作る

調査結果はチャットに流したままにせず、repo-map.mdのような小さなメモにします。公式のHow Claude remembers your projectでは、CLAUDE.mdをプロジェクトの共有指示として使えることが説明されています。ただし初回調査の詳細をいきなりCLAUDE.mdへ全部入れると重くなります。まずrepo-mapとして仮置きし、安定したルールだけ後からCLAUDE.mdへ移すのがおすすめです。

# repo-map.md

## 目的
- このリポジトリでClaude Codeを安全に使うための最初の地図

## 入口
| 種類 | ファイル | 役割 | 確認方法 |
| --- | --- | --- | --- |
| Web | site/src/pages/index.astro | トップページ | npm run build |
| Content | site/src/content/blog | 記事本文 | 記事URLを開く |

## 触ってよい候補
- docs/
- site/src/content/blog/
- 小さな表示文言

## 今日触らない領域
- .env と secrets
- 認証、決済、削除処理
- deploy scripts
- 生成済みdistやcache

## 最初の安全タスク
- 1記事のCTAを自然に直す
- 変更ファイルは1つだけ
- 検証はbuildと公開前プレビュー

## 残ったリスク
- 実運用データの流れは未確認
- 外部サービス連携は別セッションで確認する

このテンプレートは、正確なアーキテクチャ図ではなく作業の安全装置です。完璧な一覧より、「今日は何を触らないか」が書かれていることのほうが大切です。

ステップ3: 危険領域を権限でも止める

口頭で「触らないで」と言うだけでは境界になりません。Claude Codeのpermissions公式ドキュメントでは、allow、ask、denyでツール利用を制御できます。初心者が既存コードを読む初回セッションでは、読み取りと安全な確認コマンドを許し、push、削除、秘密情報読み取りは止める設定にします。

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(rg *)",
      "Bash(npm run test *)",
      "Read"
    ],
    "ask": [
      "Bash(npm run build *)",
      "Edit(site/src/content/blog/**)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(.env)",
      "Read(**/.env)",
      "Edit(scripts/deploy*)"
    ]
  }
}

このJSONは考え方の出発点です。実際のプロジェクトでは、npm run testが存在しない場合もありますし、site/src/content/blog/**以外を編集する必要がある場合もあります。大事なのは、許可を増やす前に、何を拒否するかを先に決めることです。

ステップ4: 最初の1パッチを選ぶ

repo-mapができたら、最初の作業は「小さく、戻しやすく、検証しやすい」ものにします。具体例を3つ挙げます。

1つ目は、記事やドキュメントのCTA修正です。たとえば本文末尾から商品一覧とClaude Code研修・導入相談への導線が自然につながっているかを直します。コンテンツの修正は影響範囲が読みやすく、ビルドと画面確認で検証できます。

2つ目は、READMEやCLAUDE.mdに検証コマンドを追記する作業です。初回調査で分かったbuild、test、lint、previewのコマンドを短く残すだけなら、アプリ本体を壊しにくいです。チーム導入では、この小さな整備が次回以降の時間短縮に効きます。

3つ目は、1画面の表示文言や日付フォーマットの修正です。対象ファイルを最大2つに絞り、変更前後のスクリーンショットやテストで見られるものにします。認証、決済、権限、削除処理は初回タスクから外します。

Claude Codeへ実装を頼むときは、次のように範囲を固定します。

repo-map.mdを前提に、最初の安全タスクだけ実装してください。

対象:
- site/src/content/blog/example.mdx

要件:
- 本文末尾のCTAを自然にする
- /products/ と /training/ への内部リンクを残す
- frontmatterのpubDate、category、tags、author、heroImageは変えない
- 変更ファイルはこの1つだけ

完了後に出すもの:
1. 変更したファイル
2. 変更理由
3. 実行した確認コマンド
4. 残ったリスク

ステップ5: 検証メモを機械で軽く見る

repo-mapは人間が読むメモですが、最低限の見出しがあるかはスクリプトで確認できます。次のJavaScriptは、repo-map.mdに必要な見出しが含まれているかだけをチェックします。check-repo-map.jsとして保存して実行できます。

const fs = require("node:fs");

const file = process.argv[2] || "repo-map.md";
const text = fs.readFileSync(file, "utf8");
const required = ["入口", "触ってよい候補", "今日触らない領域", "最初の安全タスク", "残ったリスク"];
const missing = required.filter((heading) => !text.includes(heading));

if (missing.length > 0) {
  console.error(`Missing repo-map sections: ${missing.join(", ")}`);
  process.exit(1);
}

console.log(`OK: ${file} has the minimum repo-map sections.`);

node check-repo-map.js repo-map.md

このスクリプトは高度な品質チェックではありません。それでも、初回調査のたびに必要項目が抜ける問題は減らせます。Claude Codeに「最後にこのスクリプトが通る形でrepo-mapを更新して」と頼めば、会話の終わりに残るメモの品質が安定します。

よくある失敗と避け方

失敗例1は、最初の依頼が広すぎることです。「全体をリファクタして」「品質を上げて」だけでは、変更範囲も完了条件も曖昧です。避け方は、読み取り専用、最大ファイル数、今日触らない領域、検証コマンドを先に指定することです。

失敗例2は、生成物やキャッシュを地図に混ぜることです。dist、.astro、.next、coverage、node_modulesのような場所を読ませすぎると、地図が大きいだけで役に立たなくなります。rg --filesで出た一覧をそのまま信じず、生成物は除外します。

失敗例3は、外部サービス連携を軽く見ることです。メール送信、決済Webhook、広告タグ、アクセス解析は、コード量が少なくても事業インパクトが大きい領域です。初回セッションでは「読むだけ」にして、編集は別タスクに分けます。

失敗例4は、最後に公開画面を見ないことです。buildが通っても、スマホ表示、コードブロック、CTA、内部リンクが崩れることはあります。記事サイトなら、ローカルまたはプレビューURLで本文、コードブロック、/products/、/training/を目視します。ここを省くと、PVが増えても収益導線が抜けたページを量産してしまいます。

この落とし穴は初心者ほど起きやすいです。Claude Codeが速く答えるほど「もう分かった気」になりますが、既存コードでは読んでいない入口、隠れた設定、外部SaaS、公開画面の崩れが最後に効いてきます。

レビューチェックリスト

既存コードにClaude Codeを入れたあとは、次の順で確認します。

観点	見ること	NG例
差分	依頼したファイルだけか	ついでの整形が大量にある
入口	変更が入口からどう効くか	読まれないファイルを直している
危険領域	認証、決済、削除、本番設定に触れていないか	.envやdeployを変更している
検証	コマンドと手動確認があるか	「たぶん大丈夫」で終わる
導線	CTAや内部リンクが自然か	商品・相談ページが本文とつながらない
引き継ぎ	残リスクが短く書かれているか	次の人が同じ調査を繰り返す

このチェックリストは、Claude Codeを疑うためではなく、作業を再現可能にするためのものです。AIの出力は速いですが、既存コードでは「何を変えなかったか」も成果物です。地図が残っていれば、次回は調査時間を短くして、より価値のある修正に時間を使えます。

収益導線まで含めて地図にする

ClaudeCodeLabのように記事から教材や相談につなげるサイトでは、コードベース地図に収益導線も入れます。どの記事が流入を取り、どこで無料PDFやテンプレートへ進み、どこで面談相談につながるのかを、コードとページの両方で見ます。実務テンプレートをまとめて使いたい場合は教材・テンプレート一覧を確認してください。チーム導入、権限設計、記事運用の仕組み化まで相談したい場合はClaude Code研修・導入相談が近道です。

repo-mapに「収益導線」を入れると、単なるコード理解で終わりません。たとえばCTA文言を直すだけの作業でも、内部リンク、広告表示、フォーム、商品ページ、計測イベントまで確認対象だと分かります。これはマネタイズ目的のサイトではかなり大事です。コードが正しくても、読者が次に進めなければ売上にはなりません。

もう1つ見落としやすいのが、成果物の保存場所です。repo-mapをチャットの中だけに置くと、次の日には別のセッションで同じ調査を繰り返します。おすすめは、docs/repo-map.mdのような恒久ファイルにせず、まずはtmp/repo-map-YYYY-MM-DD.mdのような作業メモに残すことです。いきなり正式ドキュメントにすると古くなったときの保守責任が重くなりますが、作業メモなら「今回の修正を安全に進めるための地図」として扱えます。

チームで使う場合は、repo-mapの最後に「次に聞くべき質問」を3つだけ残すと便利です。たとえば「このフォーム送信後のメールはどこで送られるか」「商品ページの価格はどのファイルが正か」「本番deployは手動か自動か」のように、次の変更で迷いそうな点を短く書きます。Claude Codeに次回依頼するときは、この3問から始めるだけで、会話がいきなり深いところから始まります。

まとめ

既存コードベースでClaude Codeを使うなら、初回45分は実装ではなく地図作りに使います。読み取り専用で棚卸しし、入口、主要ディレクトリ、危険領域、最初の安全タスク、検証コマンド、引き継ぎメモをrepo-map.mdに残します。そのあとで、1ファイルまたは最大2ファイルの小さな修正に進むと、レビューできる差分になります。

実際に試した結果、Masaの手元では、最初にrepo-mapを作ったセッションのほうが、いきなり修正を頼んだセッションより差分確認がかなり楽でした。特に記事サイトでは、コードだけでなく/products/と/training/への導線を先に地図へ入れておくことで、本文改善と収益導線の確認を同じチェックリストで回せました。