Claude Codeで他人のコードに入る最初の1時間：地図を描いてから直す

引き継ぎ初日、僕は前任者が残した社内ツールのリポジトリを開きました。READMEは3行、最後の更新は8か月前。とりあえずClaude Codeに「このプロジェクトを把握して、ログイン画面の文言を直して」と頼んだら、5分後には認証まわりの設定ファイルと、誰も触っていなかった本番デプロイ用のスクリプトまで「ついでに整理」されていました。

幸いgit statusで気づいて全部戻しました。でも、もし気づかずgit commitしていたらと思うと、いまでも背筋が寒くなります。問題はモデルの賢さではありません。僕が、どこを触っていいか分からないまま作業を任せたことです。

他人のコードに入る最初の1時間は、直す時間ではなく、地図を描く時間です。この記事では、その地図の描き方を、初めてのリポジトリでも事故らない手順としてまとめます。

この記事の要点

• 最初の1時間は「直す」のではなく「地図を描く」。触っていい場所と触ってはいけない場所を先に分ける。
• Claude Codeに任せるのは「読んで一覧化する」まで。何を保護領域にするかは人が決める。
• 修正に入る前に、必ず検証コマンド（ビルドやテスト）を1つ決めておく。これが「直った」の証拠になる。
• 最初の修正は、gitで1コマンドで戻せる小さなものに限定する。
• 把握内容は1枚のメモに残す。次に同じリポジトリへ入る人（未来の自分を含む）が同じ調査を繰り返さずに済む。

なぜ最初の1時間で事故が起きるのか

新しいリポジトリでのつまずきは、たいていコードの難しさが原因ではありません。リポジトリの形が見えていないことが原因です。

どのフォルダが画面で、どこが裏側のロジックで、どのファイルが本番の設定なのか。これが分からないまま「いい感じに直して」と頼むと、Claude Codeは善意で広い範囲を書き換えます。AIは「ここは触らないでね」と言われない限り、触っていい場所だと判断するからです。

特に引き継ぎ案件は危険です。前任者の暗黙ルール、命名の癖、なぜか残っているコメントアウト。こうした文脈はコードのどこにも書いていません。人間でも初日に全部は分かりません。だからこそ、最初にやることは編集ではなく、地図づくりになります。

地図を描く4ステップ

順番が大事です。読む範囲を決める、保護領域を決める、検証コマンドを決める、最後にやっと小さく1つ直す。この順で進めます。

ステップ1：今日のゴールを一文で書く

「このプロジェクトを理解する」では広すぎます。Claude Codeも人も、広いゴールでは止まる場所を見失います。

代わりに、こう書きます。「ログイン画面の文言を1か所だけ直し、ビルドが通ることを確認する」。一文で言えるゴールは、終わったかどうかも一目で分かります。

ステップ2：読む範囲と触ってはいけない範囲を分ける

ここが地図の中心です。Claude Codeに「全部読んでいい」と渡す前に、触ってはいけない場所を先に言葉にします。

僕が毎回保護領域に入れるのは、認証、課金、環境変数ファイル（.env）、本番デプロイのスクリプトです。これらは間違えると被害が大きく、しかも戻しにくい。だから最初は「読むのはいいが書くな」と明示します。

ステップ3：検証コマンドを先に決める

「直りました」と言われても、何をもって直ったと言えるのか。それを先に決めておきます。

多くのプロジェクトでは、ビルドコマンドかテストコマンドが検証になります。npm run buildが通る、npm testが緑になる。この1コマンドを修正の前に決めておくと、Claude Codeの「できました」を鵜呑みにせず、機械の合否で判断できます。

ステップ4：戻せる小さな修正を1つだけ

地図ができたら、最初の修正は欲張らないことです。文言の修正、コメントの追加、明らかなタイポ直しのような、git checkout一発で戻せるものを1つ選びます。

「ついでにあれも」を我慢する。大きな差分は誰もレビューできず、事故ったときの戻しも大変になります。

Claude Codeに任せる範囲と、人が決める範囲

地図づくりで何を任せ、何を自分で握るか。ここを混ぜると冒頭の事故が起きます。

作業	担当	理由
ファイル一覧やフォルダ構造の把握	Claude Code	機械的な読み取りは速くて正確
「この機能はどこにある？」の調査	Claude Code	検索と要約が得意
何を保護領域にするか	人	被害の大きさは文脈依存。AIは知らない
検証コマンドの最終決定	人	プロジェクト固有の事情を知っているのは人
本番・課金・認証への変更	人	戻しにくい操作は人が承認する

原則はシンプルです。読むこと・一覧化することは任せる。戻しにくい判断は人が握る。 安全だと確認できた操作だけ、あとからClaude Codeに格上げしていきます。

権限の細かい設計は別記事にまとめています。最初に何を止めるか迷ったら 権限ガイド を見てください。

コピペで使える地図づくりプロンプト

最初の1時間で僕が実際に投げているプロンプトです。そのまま貼って、リポジトリ名だけ自分のものに変えてください。

このリポジトリを初めて触ります。まだ何も編集しないでください。
以下を順番に調べて、結果を箇条書きで報告してください。

1. トップレベルのフォルダ構成と、それぞれの役割（推測でよいが推測と明記）
2. ビルド・テスト・起動に使うコマンド（package.json や README から）
3. 認証・課金・環境変数・本番デプロイに関係するファイルの場所
4. 「ログイン画面の文言」がどのファイルにあるか

報告のあと、3のファイル群は今回「読むだけ・編集禁止」とします。
編集してよいのは4で見つけたファイル1つだけです。

ポイントは、最初の一行で「まだ編集するな」と釘を刺すことです。これがないと、調査のついでに直し始めるAIがいます。

コピペで動く検証スクリプト

地図ができたら、修正の前後で同じチェックを回せるようにしておくと安心です。次のスクリプトは、変更前後でビルドが通るかと、差分が広がりすぎていないかを確認します。Node.jsで動きます。

// verify-edit.mjs
// 修正前後でビルドが通るか、差分が想定より大きくないかを確認する
import { execSync } from "node:child_process";

// 1コマンドで戻せる範囲か、変更ファイル数の上限を決めておく
const MAX_CHANGED_FILES = 3;

function run(cmd) {
  return execSync(cmd, { encoding: "utf8" }).trim();
}

try {
  // 変更されたファイルの数を数える
  const changed = run("git diff --name-only")
    .split("\n")
    .filter(Boolean);

  console.log(`変更ファイル数: ${changed.length}`);
  changed.forEach((f) => console.log(`  - ${f}`));

  if (changed.length > MAX_CHANGED_FILES) {
    console.error(
      `差分が広すぎます（${changed.length} > ${MAX_CHANGED_FILES}）。`,
    );
    console.error("一度 git checkout で戻し、修正を小さく分けてください。");
    process.exit(1);
  }

  // 保護領域に手が入っていないかを確認する
  const protectedHits = changed.filter((f) =>
    /(^|\/)\.env|auth|billing|deploy/i.test(f),
  );
  if (protectedHits.length > 0) {
    console.error("保護領域に変更が入っています:");
    protectedHits.forEach((f) => console.error(`  - ${f}`));
    process.exit(1);
  }

  // ビルドが通るかを確認する（プロジェクトに合わせて差し替え）
  console.log("ビルドを確認します...");
  run("npm run build");
  console.log("ビルドOK。修正は安全範囲に収まっています。");
} catch (err) {
  console.error("検証に失敗しました:", err.message);
  process.exit(1);
}

node verify-edit.mjs で実行します。変更ファイルが多すぎたり、保護領域に手が入っていれば、その場で止まります。冒頭の「認証ファイルまで整理された」事故は、このスクリプトを通していれば未然に止まったはずです。

効く場面を3つ

具体的にどんなリポジトリで使えるか、僕が試した3パターンを挙げます。

1. 引き継いだ社内ツール ドキュメントがないコードベースに入るとき。まずフォルダ構成と起動コマンドを一覧化させ、認証と設定ファイルを保護領域に固定します。最初の修正は管理画面のラベル変更など、見た目で結果が分かるものにします。

2. 公開リポジトリへの初コントリビュート 他人のオープンソースに初めてPull Requestを出すとき。テストコマンドを先に特定させ、npm testが緑のまま小さな修正を1つ出す。広い改善提案より、戻せる1ファイル修正のほうが取り込まれやすいです。

3. 古いプロジェクトの再起動 半年放置したコードを再開するとき。「どこまで動くか」をClaude Codeに調べさせ、壊れている入口を地図化します。直すのは、いちばん戻しやすい1か所からにします。

落とし穴と直し方

落とし穴1：一度に全部直そうとする 「ついでにリファクタも」で差分が50ファイルに膨らむと、誰もレビューできません。直し方は、上の検証スクリプトで変更ファイル数に上限を設けること。超えたら一度戻して分割します。

落とし穴2：ビルド成功だけで完了にする ローカルでビルドが通っても、画面が想定どおりとは限りません。文言修正なら、実際にその画面を開いて文字を目で確認するまでが1セットです。

落とし穴3：保護領域を口頭だけで伝える 「認証は触らないで」とプロンプトで言っても、長い作業の途中で忘れられることがあります。直し方は、検証スクリプトで保護領域への変更を機械的に弾くこと。人の記憶ではなく、コマンドで守ります。

落とし穴4：調べた地図を残さない せっかく1時間かけて把握しても、メモを残さないと次回また同じ調査をします。フォルダ構成、検証コマンド、保護領域を1枚のメモに書いておくと、未来の自分が助かります。

その地図メモは、プロジェクトのルールとして CLAUDE.md に書いておくとさらに効きます。書き方は CLAUDE.mdベストプラクティス にまとめました。

よくある質問

Q. 最初の1時間、本当に何も直さなくていいんですか？ A. 直しても構いませんが、直すのは「戻せる小さな1か所」だけにします。残りの時間は地図づくりに使うほうが、結果的に事故が減って速いです。

Q. Claude Codeに「全部読んでいい」と渡すのは危険ですか？ A. 読むだけなら危険ではありません。危ないのは「書く」権限です。読み取りは広く、書き込みは狭く。これが基本の分け方です。

Q. 検証コマンドが分からないプロジェクトはどうすれば？ A. まずClaude Codeに package.json やREADMEから候補を挙げさせます。それでも不明なら、いったん git status で差分が出ないことだけを最低限の検証にします。

Q. PowerShellでも同じことができますか？ A. できます。git diff --name-only の結果を数えて上限と比べるロジックは、PowerShellでもそのまま書けます。検証スクリプトは使う環境に合わせて書き換えてください。

Q. この手順は初心者でも回せますか？ A. 回せます。むしろ初心者ほど効きます。コードを完全に理解していなくても、「触っていい場所」を先に決めれば大事故は防げます。基礎から固めたい人は 入門ガイド を先に読むとスムーズです。

実際に試した結果

この手順は、冒頭の事故のあとに僕が自分用に作ったものです。試してみて一番効いたのは、検証スクリプトで「変更ファイル数の上限」と「保護領域の自動チェック」を入れたことでした。

実際、引き継いだリポジトリで3回ほど回したところ、1回は変更ファイル数が上限を超えて止まりました。中身を見ると、Claude Codeが文言修正のついでに共通コンポーネントまで書き換えていて、もし通していたら影響範囲が読めない差分になっていました。止まってくれたおかげで、修正を2つに分けて出せました。

「賢いAIに任せれば大丈夫」ではなく、「転んでも戻せる範囲で任せる」。地図を先に描くだけで、最初の1時間の手触りがまるで変わりました。エンジニアでない人がチームでこの分け方を共有したい場合は、非エンジニア向けの入り口 も役に立ちます。

Claude Codeの公式な使い方は Anthropic公式ドキュメント でも確認できます。手元の運用ルールを固めて、チームで再現できる形にしたい人は、研修・相談 で具体的なリポジトリを一緒に地図化していきます。