Claude Codeで既存リポジトリの最初の1編集を安全にする導入手順

引き継いだばかりの社内リポジトリで、僕は初日にやらかしました。

「とりあえず全体を読んで、気になるところ直しといて」とClaude Codeに頼んだら、30分後に23ファイルが書き換わっていた。中身は悪くない。でも、本番のデプロイ設定と、誰も触ってはいけない決済まわりのファイルまで「ついでに」整理されていました。差分が大きすぎて、どこが本当に必要な変更か僕にも分からない。結局、全部捨ててやり直しました。

賢いAIが事故るのは能力の問題ではありません。入る前に「どこまで触っていいか」を誰も決めていなかっただけです。今日はその一日目を、戻せて、確認できて、最後まで終わる形に作り替えます。

この記事の要点

• 他人のコードに初めて入る日は、まず「読んでいい場所・触ってはいけない場所・終わったら走らせる検証コマンド」を1ページにまとめる。
• Claude Codeに最初から大改修を任せない。戻せる小さな1編集（テスト名の整理、コメント追加など）から始める。
• 「できました」の報告の前に、必ず検証コマンドを1つ走らせ、その結果を残す。
• 削除・本番DB・課金・force pushは初日は全部「人間に確認」に固定し、安全と分かったものだけ後から自動化する。
• 差分が膨らみ始めたら、依頼文をいじるより先に「触れるファイルを減らす」。

なぜ初日に範囲を決めるのか

新しいリポジトリは、地図のない街です。どのファイルが心臓部で、どれが触ると壊れるか、最初は誰にも見えません。

ここでClaude Codeに「全体を見て直して」と頼むと、AIは親切心で広く手を入れます。AIが悪いのではありません。範囲を渡さなかった人間の側に原因があります。初めてのアルバイトに「店、いい感じにしといて」と言って、レジの設定まで変えられたら、それは指示した側の問題ですよね。

だから最初にやるのは賢いプロンプトを書くことではなく、地図を1枚描くことです。読んでいい棚、開けてはいけない引き出し、帰る前に確認する戸締まり。この3つを紙に書くだけで、初日の事故はほとんど消えます。

最初に決める3つの境界

順番が大事です。上から固定していきます。

決めること	具体例	なぜ先に決めるか
読んでいい場所	src/、docs/、テストファイル	全部読ませると無関係な変更を提案しがち
触ってはいけない場所	.env、決済、認証、DBマイグレーション、本番デプロイ設定	ここを壊すと取り返しがつかない
終わったら走らせる検証	npm run build、テスト1本	「動く証拠」を毎回残すため

この3つを書いた紙（テキストでもいい）を、僕は作業フォルダのONBOARDING.mdに置いています。Claude Codeに最初に読ませるのもこのファイルです。地図を共有してから街を歩かせる、という順番です。

AIに任せる範囲と、人が判断する範囲

ここを混ぜると事故ります。線引きをはっきりさせます。

Claude Codeに任せていい仕事

• リポジトリ全体をざっと読んで構造を要約する
• 「この機能はどのファイルにあるか」を探す
• テスト名の整理、コメント追加、型の補完など、戻せる小改善の下書き
• 検証コマンドを実行し、失敗ログを読んで原因の見当をつける

人間が必ず判断する仕事

• 触ってはいけない領域に入る変更を許すかどうか
• ファイルの削除、本番DBへの操作、課金処理、force push
• 大きな設計変更をマージしていいかの最終判断
• 差分が想定より広がったときに止めるかどうか

僕の基準はシンプルです。「間違えてもgitで戻せること」はAIに任せる。「戻せないこと」は人間がボタンを押す。この一線だけ守れば、初日から大崩れはしません。

コピペで使えるプロンプト雛形

最初の編集に入る前に、僕はこれを投げます。いきなり書かせず、まず計画を返させるのがコツです。

これは初めて触る既存リポジトリです。次のルールを守ってください。

【読んでいい】src/ と docs/ とテストファイルのみ
【触らない】.env / 認証 / 決済 / DBマイグレーション / 本番デプロイ設定
【今回のゴール】戻せる小さな改善を1つだけ（例: テスト名の整理）
【検証】変更後に必ず `npm run build` を走らせ、結果を貼る

まだコードは変更しないでください。
最初に「どのファイルをどう直すか」の計画と、上のルールを
あなた自身の言葉で言い直したものを返してください。

返ってきた計画が、こちらの制約をちゃんと言い直していれば合格です。範囲を広げようとしていたら、その場で止めます。計画が良ければ「ではその通りに、build まで実行して」と進めます。

境界をコードで持っておく

紙のルールは忘れます。だから僕は導入計画を機械が読める形でも残しています。下のスクリプトはそのまま動きます。自分のリポジトリ用に中身を置き換えて使ってください。

#!/usr/bin/env bash
# 既存リポジトリ導入計画を1つのJSONにまとめる
set -euo pipefail

cat > onboarding-plan.json <<'JSON'
{
  "goal": "既存リポジトリで最初の1編集を安全に終える",
  "readOnlyCommands": [
    "git status --short",
    "git ls-files | head -50",
    "grep -rn \"TODO\\|FIXME\" src | head -20"
  ],
  "protectedAreas": [".env", "billing", "auth", "db/migrations", "deploy/prod"],
  "firstTask": "戻せるドキュメントまたはテストの小改善を1つ",
  "proofCommand": "npm run build",
  "rollback": "git diff -- path/to/changed-file && git checkout -- path/to/changed-file"
}
JSON

echo "=== 導入計画 ==="
cat onboarding-plan.json

echo ""
echo "=== 現在の差分（空なら未編集）==="
git status --short

このスクリプトは派手ではありません。価値は、作業に入る前に「禁止領域」と「証拠コマンド」をファイルに固定できることです。protectedAreasを自分のリポジトリの危険な場所に書き換えるだけで、初日の地図ができます。

検証コマンドも1つ用意しておくと安心です。Node.jsのプロジェクトなら、こんな最小チェックで「壊れていないか」を機械的に確認できます。

// check.mjs : ビルドが通るかだけを確認する最小スクリプト
import { execSync } from "node:child_process";

try {
  // 自分のプロジェクトの検証コマンドに置き換える
  execSync("npm run build", { stdio: "inherit" });
  console.log("検証OK: ビルドが通りました。差分をレビューしてください。");
} catch (e) {
  console.error("検証NG: ビルドが落ちました。マージせず原因を確認します。");
  process.exit(1);
}

node check.mjsが緑なら差分をレビューに回す、赤なら止める。この一本があるだけで、「動いてるはず」という思い込みでマージする事故が消えます。

3つの現場での使い方

近い状況があれば、手順を作り直さず名前だけ自分の現場に置き換えてください。

1. コンテンツサイトの引き継ぎ 記事データの置き場所、画像フォルダ、ビルドコマンド、商品ページを先に読ませて把握させる。最初の編集は「壊れたリンクの修正1件」だけ。ビルドが通ったらレビューに出す。本文の大量書き換えは、安全だと分かってから。

2. SaaSのコードベース 認証・課金・DBマイグレーションを禁止領域に明記する。最初のタスクは「テストの説明文を分かりやすくする」程度に絞り、人が承認してから進める。ここを甘くすると、決済ロジックに「親切な改善」が入って肝を冷やします。

3. 古いレガシーリポジトリ 「全体を近代化して」は禁句です。差分が読めない大きさになります。代わりに、関数名のtypo修正やテスト名の整理など、ビルドで検証できる小さな一歩から。1回成功したら、同じ型で次の一歩を踏みます。

どの例にも「止めどころ」があります。止めどころがあるから、作業が無限に広がりません。

失敗例と、その直し方

正直に書きます。最初の数回は全部やらかしました。

禁止領域を書かずに頼んだ → レビューできない大きさの差分になり、全部捨てる羽目に。直し方は単純で、依頼文を練り直すより先に「読んでいいファイルを減らす」。範囲が狭いほど、AIの暴走幅も狭くなります。

変更が全部終わってからビルドした → どの編集で壊れたか分からなくなりました。今は1ファイル直すごとに検証を走らせます。壊れた瞬間が記録に残るので、原因がすぐ分かります。

確認を自分の目だけに頼った → 忙しい日に必ず見落とします。文字どおり「機械でわかること」は機械に任せる。ビルドの可否、テストの結果、リンク切れ。人間の目は、機械が拾えない設計判断だけに使う。これで夜中のレビューがぐっと減りました。

落とし穴を記事に残すのは、読者が成功例だけでは自分の危ない状態に気づけないからです。どの依頼が広がりすぎたか、どの検証が抜けていたかを短く残すと、次の自分が同じ穴を踏みません。

よくある質問

Q. 最初の1編集は、何を選べばいいですか？ A. 「間違えてもgit checkoutで戻せること」を選んでください。テスト名の整理、コメント追加、誤字修正あたりが安全です。新機能や設定変更は初日には向きません。

Q. 禁止領域はどこまで細かく書くべきですか？ A. 「壊れると取り返しがつかない場所」だけで十分です。.env、認証、課金、本番デプロイ設定、DBマイグレーション。最初はこの5つを押さえれば、致命的な事故はほぼ防げます。

Q. Claude Codeに計画を返させる手間は省けませんか？ A. 省かないことをおすすめします。計画を言い直させる一手間で、範囲のズレを編集前に発見できます。コードが書かれてから気づくより、はるかに安いコストです。

Q. 検証コマンドはビルドだけで足りますか？ A. 初日はビルド1本で十分です。慣れてきたら、関連するテスト1本を足す。最初から全テストを回そうとすると重くて続きません。小さく始めて、成功ログがたまってから増やします。

Q. チームに導入するときの注意は？ A. ONBOARDING.mdのような共有ファイルに境界を書き、全員が同じ地図を使うことです。人によって禁止領域がバラバラだと、レビューの基準も揺れます。

関連記事

考え方の土台はClaude Codeをエンジニア以外が使う方法とClaude Code はじめの一歩ガイドが参考になります。プロジェクトのルールを覚えさせる作法はCLAUDE.md ベストプラクティスに、より踏み込んだ指示の出し方はプロンプト設計の実践にまとめています。権限まわりの細部はAnthropic公式ドキュメントも合わせて確認してください。

実際に試した結果

冒頭の「23ファイル事故」のあと、僕は導入の順番を変えました。賢いプロンプトを探すのをやめて、先にonboarding-plan.jsonで禁止領域と検証コマンドを固定する。これだけで、決済や本番設定に手が入る事故はゼロになりました。

最初の1編集を「テスト名の整理」に絞った日は、差分が8行で収まり、ビルドも一発で通りました。レビューに2分もかかりません。逆に、範囲を決めずに頼んだ別の日は、また差分が膨らんで全部捨てています。違いはモデルの賢さではなく、入る前に地図を描いたかどうかでした。

他人のコードを安全に触る型を、自分のチームの実例で固めたい方は、業務に合わせた導入の進め方を研修・相談で一緒に組み立てています。まずは今日、自分のリポジトリの禁止領域を5つ書き出すところから始めてみてください。