Claude Codeで他人のリポジトリを最初の30分で地図化する手順

転職して3日目、引き継ぎ資料ゼロの社内リポジトリを渡されたとき、僕はやってしまいました。

「このバグ直しといて」と言われ、Claude Codeに丸投げしたんです。Claudeは元気よく8ファイルを開いて、認証まわりのコードまで“ついでに”整理し始めました。直したかったのはフッターの表示崩れ、1ファイルで終わる話だったのに。

初めて触るコードに、いきなり修正させてはいけない。最初に作るのは実装じゃなくて、地図です。

この記事の要点

• 初見のリポジトリは「編集禁止」で読ませる。最初の成果物は修正コードではなく、入口・コマンド・危険領域・最初の小タスクを並べた repo map。
• repo mapはコピペできる1つのプロンプトから始まる。Claudeに「方向確認のためだけに読め、まだ編集するな」と最初に宣言する。
• 最初のタスクは「触るファイルが少ない・検証コマンドがある・認証や課金に触らない」の3条件で選ぶ。賢そうな大改修は後回し。
• 地図は使い捨てにせず CLAUDE.md に要約しておく。翌日の自分とレビュアーが同じ前提で話せる。
• ハマりどころは「安全なコマンドを決めずに走り出すこと」。何が成功の証拠かを先に握る。

なぜ「地図づくり」から始めるのか

コンテキストの節約、というのが教科書的な答えです。でも僕が地図を作る本当の理由はそこじゃありません。

初見のリポジトリでいちばん怖いのは、自分が境界を知らないことです。どこが認証で、どこが課金で、どのファイルを消すと本番が落ちるのか。それを知らないままClaude Codeに「いい感じに直して」と言うのは、間取りも知らない他人の家で電動ドリルを振り回すようなものです。

repo mapは、その家の間取り図です。入口（エントリーポイント）はどこか、安全に押せるボタン（コマンド）はどれか、触ると危ない部屋（認証・課金・マイグレーション）はどこか。これを先に1枚にまとめておくと、相談する相手も、レビューする人も、翌日の自分も、同じ前提で話せます。

特にインストール直後の人は、「で、最初に何を任せればいいの?」で固まりがちです。そこを地図で埋める。コマンドの全体像は既存コードを読む最初のプロンプト7選で、会話が長くなって精度が落ちる問題はコンテキスト管理の記事で補完できます。

編集を禁止して読ませる、最初の30分

手順はいつも同じです。順番が大事なので番号で書きます。

1. 編集を禁止する。 最初のプロンプトで「読むだけ」と宣言する。Claude Codeは放っておくと賢そうに大量修正を始めるので、その前に人間が境界を握る。
2. 読む対象を絞る。 README、package.json、ルーティング、テスト、デプロイ設定。この5つだけで、リポジトリの骨格はだいたい見える。
3. コマンドを安全・危険で仕分ける。 npm run build は安全。npm run db:reset は危険。動かす前に色分けする。
4. 最初の1タスクを選ぶ。 ファイル数が少なく、検証コマンドがあり、認証や課金を触らないもの。賢く見えるタスクではなく、転んでも戻せるタスクを選ぶ。

この順番なら、Claude Codeが暴走する前に作業の範囲を人間が決められます。逆に言うと、ここを飛ばして「機能を作って」と頼んだ瞬間、境界が曖昧なまま複数モジュールへ被害が広がります。

コピペできる最小セット

まず、方向確認だけをさせるプロンプト。これをそのまま貼ってください。Do not edit files yet. の1行が効きます。

Read this repository for orientation only.
Do not edit files yet.
Return:
1. the main app entry points
2. the commands that appear safe to run
3. the files that define content, routes, and tests
4. three small first tasks ranked by verification cost
5. one risk that should block a larger change

返ってきた内容は、こういうYAMLに整形して残します。頭の中だけに置かず、ファイルにする。これが地図の本体です。

repo_map:
  entry_points:
    - package.json
    - src/main.ts
  safe_commands:
    - npm run build
    - npm test
  first_task_rule:
    max_files: 3
    proof_required: true
    avoid_auth_and_billing: true

「最初のタスクをどう選ぶか」を勘に頼ると、結局いちばん面白そうな（=危ない）タスクを選んでしまいます。だから僕は点数化しています。リスク・変更ファイル数・検証の速さを足し引きして、数字が小さいものから着手する。

// 最初のタスクを「安全さ」で点数化する。数字が小さいほど先に着手してよい。
export function rankFirstTask(task) {
  // 認証や課金に触るタスクは問答無用で高リスク(+10)
  const risk = task.touchesAuth || task.touchesBilling ? 10 : 0;
  // 触るファイルが多いほどスコープが広い(1ファイルあたり+2)
  const scope = task.filesChanged * 2;
  // 速い検証手段(テスト等)があれば下げる(-3)、無ければ上げる(+4)
  const proof = task.hasFastProof ? -3 : 4;
  return risk + scope + proof;
}

この関数の良いところは、「なんとなく簡単そう」を数字に翻訳してくれることです。touchesBilling が立っただけで +10 されるので、課金まわりの“ちょっとした修正”は自動的に後回しになります。

実際のリポジトリでどう地図化するか

抽象論だけだと使えないので、僕が実際に当てはめている型を3つ。

Astroのコンテンツサイトの場合。 まず src/content、src/pages、BlogPostLayout、そして build コマンドを地図化します。このサイト自体がそうで、記事を1本足すときも「どのコレクションに入るか」「buildが通るか」を先に確認します。entry pointは astro.config と各 pages、危険領域は基本ありませんが、強いて言えばデプロイ設定です。

SaaSアプリの場合。 auth、billing、migration の3つを最初から危険領域に塗ります。そして最初のタスクには、README修正やテスト追加みたいな“本番に絶対に影響しないもの”を選ぶ。rankFirstTask でいえば、認証に触れた瞬間スコアが跳ね上がるので、自然とそうなります。

チームに導入する場合。 作った地図を CLAUDE.md に短く要約して置きます。これをやっておくと、次の担当者が同じ探索を一からやり直さずに済む。地図はあなた個人のメモではなく、チームの共有資産になります。CLAUDE.md の設計は既存コードベース地図を作る記事で詳しく掘り下げています。

僕がやらかした失敗3つ

正直に書きます。地図づくりを覚える前、僕はこの3つで時間を溶かしました。

ひとつ目は、冒頭の話。いきなり「この機能を作って」と頼んだこと。 境界が曖昧なまま、Claudeは関係ないモジュールまで“改善”を広げました。フッター1行の修正のはずが、差分レビューで30分溶けた。最初に「読むだけ」と言うだけで防げたのに、です。

ふたつ目は、安全なコマンドを決めずに走り出したこと。 何が成功の証拠なのか曖昧なまま進めた結果、「buildが通れば正解なのか、テストなのか、それともDBの状態なのか」が分からなくなりました。証拠コマンドを先に1つ決める。それだけで、完了したかどうかの判断が一瞬になります。

みっつ目は、地図を残さなかったこと。 その日は頭に入っているからメモを取らなかった。翌朝、まったく同じ探索をもう一度やる羽目になりました。トークンも時間も二度払い。地図は数行でいいから必ずファイルに書く、を今は徹底しています。

地図を引き継ぎメモに変える

地図は、その日のうちに使い切るものではありません。価値が出るのは、翌日の確認や別の人のレビューのときです。だから僕は、作業の最後に短い引き継ぎ（handoff）を残します。

書く内容はシンプルで、「何を変えたか」だけでなく、なぜその範囲に絞ったか・どの証拠を見たか・次に失敗しそうな場所はどこか。たとえば記事を1本直したなら、改善した段落、足した内部リンク、外部リンク、heroImage、公開URLで確認したh1、これだけ並べておけば十分です。

このメモがあると、あとで「PVは増えたのに登録が増えない」みたいな問題が起きたとき、CTAの問題なのか、テーマの問題なのか、検証の漏れなのかを切り分けられます。地図と引き継ぎはセットで効きます。

外部の一次情報も地図に添えておくと強いです。Claude Codeの読解系ワークフローは公式の common-workflows ドキュメントが出発点として確実なので、僕はここを地図の脚注に貼っています。

よくある質問

Q. repo mapは毎回作るんですか? A. 初見のリポジトリでは必ず作ります。一度作った地図は CLAUDE.md に残すので、2回目以降は差分の確認だけで済みます。ゼロから作り直すのは初回だけです。

Q. 「読むだけ」と言ってもClaudeが編集しようとしたら? A. プロンプトの先頭に Do not edit files yet. を置き、それでも不安なら権限設定で書き込みを止めます。最初の地図化フェーズは、物理的に編集できない状態にしておくのが一番安全です。

Q. 最初のタスクはどれくらい小さくすべき? A. 触るファイル3つ以内が目安です。rankFirstTask の max_files: 3 がこの基準。READMEの誤字修正やテスト1本追加くらいで十分で、それで検証フローが回ることを先に確かめます。

Q. 大規模なモノレポでも同じやり方で通用しますか? A. 基本は同じですが、入口を「触る予定のパッケージ1つ」に限定します。リポジトリ全体ではなく、担当する一画だけを地図化する。広く読む手順は大規模コードベースを迷わず読むガイドが参考になります。

Q. 地図づくりにどれくらい時間をかける? A. 30分が目安です。これ以上かけるなら、それはもう地図化ではなく実装に踏み込んでいるサインなので、一度手を止めて最初のタスクを1つ選びます。

実際に試した結果

冒頭の“認証コードまで整理された”事故以来、僕は初見のリポジトリで「いきなり直す」のを完全にやめました。

代わりに最初の30分を地図づくりに使う。Do not edit files yet. で読ませて、入口とコマンドと危険領域をYAMLに落とし、rankFirstTask で最初の1タスクを選ぶ。たったこれだけで、関係ないファイルへ被害が広がる事故はゼロになりました。地図を CLAUDE.md に残すようになってからは、翌日の「あれ、これどこだっけ」も消えました。

遠回りに見えて、初日に地図を描くのがいちばん速い。これが今の僕の実感です。Claude Codeに任せる作業の型をもっと固めたい人は、教材一覧に日々のコマンドや指示テンプレートをまとめています。チーム導入や権限設計まで踏み込むなら導入相談からどうぞ。