Claude Codeで複数ファイルの変更を安全に進めるコツ

Claude Codeの公式ドキュメントは「変更が複数ファイルにまたがる場合（when the change modifies multiple files）」をPlan Modeを使うべき明確な基準として挙げています。複数ファイルの変更はClaude Codeが最も破綻しやすい場面の一つです。影響範囲の読み違え、変更順序のミス、中間状態での停止——これらを防ぐには段階的な進め方が必要です。この記事では複数ファイル変更の安全な4ステップを整理します。

複数ファイル変更が難しい理由

単一ファイルの変更とは異なり、複数ファイルの変更には次の課題があります。

• 依存関係の見落とし: Aを変えるとBも変えなければいけないのに、Bを見逃す
• 不整合な中間状態: AとBを順番に変えるとき、Aだけ変えた状態でテストするとエラーになる
• ロールバックの複雑さ: 何ファイルも変えた後で「やっぱり戻す」が大変
• コンテキスト消費: 多くのファイルを読み込むとウィンドウが埋まる

これらは「丸投げして一発でやらせる」アプローチでは必ず発生します。

ステップ1：影響範囲をサブエージェントで調査する

変更の実装前に、影響を受けるファイルを正確に把握することが最初の仕事です。ここに調査コストをかけることで、後の手戻りを防げます。

調査はサブエージェントに委譲するのが効率的です。調査の過程で大量のファイルを読み込んでも、メインコンテキストには結果サマリーしか返ってこないからです。

サブエージェントを使って次を調査してください：
- src/api/users.ts のシグネチャ変更（getUserById の引数に options を追加）
  が影響するファイルをすべて列挙する
- 直接的な呼び出し元と、間接的な依存（型定義・テスト・スタブ）を分けて示す
- 400字以内でまとめる

調査結果が返ってきたら、変更するファイルリストを確定します。このリストが後の変更計画の土台になります。

ステップ2：Plan Modeで変更計画を作る

影響範囲が確定したら、実際の変更に入る前にPlan Modeで計画を作ります。

または実行中のセッションで Shift+Tab を押してPlan Modeに切り替えます。

計画依頼のテンプレート

以下のファイルを順番に変更する計画を作ってください。

変更の目的：
getUserById の引数に options?: { includeDeleted?: boolean } を追加する

影響ファイル（調査済み）：
- src/api/users.ts（実装）
- src/types/api.ts（型定義）
- src/services/userService.ts（呼び出し元）
- tests/api/users.test.ts（テスト）
- tests/mocks/userMock.ts（スタブ）

計画に含めること：
1. 変更する順序とその理由
2. 各ファイルの変更内容の概要
3. 中間テストのタイミング
4. ロールバックが必要なときの方針

実装はしないこと。計画だけを出力すること。

Ctrl+G を押すと計画をテキストエディタで直接編集できます。

良い変更順序の原則

計画を確認するときは変更順序に注目します。

型定義→実装→呼び出し元→テストの順が基本です。この順序を守れば、TypeScriptの型チェックがコンパイルエラーとして残りの変更が必要な箇所を教えてくれます。

ステップ3：1ファイルずつ変更してテストする

計画が確定したら実装フェーズに移ります。鉄則は「一度にすべて変えない」です。

変更→テスト→コミットのサイクル

計画の1番目：src/types/api.ts の型定義を変更してください。

変更後に次のコマンドを実行して確認してください：
npx tsc --noEmit

エラーが出た場合は、この型定義のスコープ内で解決してください。
他のファイルの変更はまだしないこと。

1ファイルの変更が完了してコンパイルエラーがないことを確認したら、コミットします。

中間コミットのメリットは2つあります。

1. ロールバックポイントが増える: 後のステップで問題が起きたとき、この時点まで戻ってやり直せる
2. 差分が小さくなる: 1コミット=1ファイルの変更なので、レビューがしやすい

変更中の依頼文テンプレート

計画の2番目：src/api/users.ts の実装を変更してください。

制約：
- options パラメータはオプショナルにする（既存の呼び出しを壊さない）
- options が渡された場合は WHERE deleted_at IS NOT NULL の条件を追加する
- テストファイルはまだ変えないこと

完了条件：
- npx tsc --noEmit がエラーなしで通る
- 既存のユニットテストが通る（失敗が増えることは想定内）

各ステップで「このファイルだけ」という制約を明示することが重要です。Claude Codeはコンテキストから関連ファイルを自動的に変えようとする傾向があります。スコープを依頼文で制限することで予期しない変更を防げます。

ステップ4：ロールバック方針を事前に決める

複数ファイルの変更には必ずロールバック方針を用意します。

git restore で単一ファイルを元に戻す

特定のファイルだけを直前のコミット状態に戻します。

git reset --soft で複数コミットをまとめてやり直す

git reset --soft HEAD~3  # 直前の3コミットを取り消す（変更は残る）

中間コミットを積んでいれば、途中まで戻ってやり直せます。--soft を使えばファイルの変更内容は残るため、再コミットが容易です。

/rewind でClaude Codeの変更を巻き戻す

Claude Codeが加えた変更をチェックポイント単位で巻き戻します。Gitとは独立した仕組みなので、git reset と組み合わせて使えます。

Worktreeで安全に並行実験する

変更を本流ブランチと切り離した作業ツリーで試せます。実験が失敗してもメインブランチへの影響がなく、--worktree オプションで独立した環境が作れます。

失敗パターンと対処

パターン1：中間状態でビルドが壊れる

症状: 型定義だけ変えた状態でテストを走らせたらエラーが大量発生した。

対処: 型定義の変更後にテストを走らせるのは早すぎます。すべての呼び出し元を変更し終えるまでテストスイートは実行しないようにするか、型定義変更時は npx tsc --noEmit だけを中間確認として使います。

パターン2：Claude Codeがスコープ外のファイルを変え始める

症状: 依頼したファイル以外も変更し始めた。

対処: 依頼文に「src/api/users.ts だけを変えること。他のファイルは変えないこと」と明示します。Plan Modeで計画を確定してから実装に移ることで予防できます。

パターン3：変更が多すぎてコンテキストが埋まる

症状: 変更の途中でClaude Codeの応答が遅くなったり、前の指示を忘れた様子がある。

対処: /compact で会話を圧縮するか、いったん /clear してから残りのファイルを別セッションで変更します。変更計画を NOTES.md に書き出しておけば /clear 後もコンテキストを復元できます。

複数ファイル変更の依頼前チェックリスト

• 影響ファイルをサブエージェントで調査済みか
• Plan Modeで変更計画を確認したか
• 変更順序は「型定義→実装→呼び出し元→テスト」になっているか
• 1ファイルずつ変更して中間テストをするか
• 中間コミットのタイミングを決めているか
• ロールバック手段（git restore/git reset --soft//rewind）を把握しているか
• 各ステップの依頼文にスコープを明示しているか

次に読むおすすめ記事：

• 「Claude Codeで既存コードを壊さずリファクタリングする依頼文」：複数ファイル変更でよく行うリファクタリングの安全な依頼テンプレート
• 「Claude Codeに「計画してから実装」させるプロンプト例」：Plan Modeの詳細な使い方と計画レビューの観点