Claude Codeで複数ファイル同時編集｜大規模変更を安全に実行するテクニック

ソフトウェア開発では、1つの変更が複数のファイルに波及することが珍しくありません。関数名の変更、APIレスポンスの構造変更、設計パターンの刷新など、プロジェクト全体にまたがる変更は手作業では膨大な時間とリスクを伴います。Claude Codeは、こうした複数ファイルにわたる大規模変更を、整合性を保ちながら安全に実行できる強力なツールです。本記事では、クロスファイルリファクタリングの実践テクニックから、安全なロールバック戦略まで詳しく解説します。

複数ファイル編集が必要になるケース

日常的に発生するクロスファイル変更

開発現場で複数ファイルの同時編集が必要になるケースは、想像以上に多く存在します。代表的なものを挙げてみましょう。

• 関数・変数のリネーム：ユーティリティ関数の名前を変更すると、その関数を呼び出しているすべてのファイルを更新する必要がある
• APIレスポンスの構造変更：バックエンドのレスポンス形式を変えると、フロントエンドの受け取り側も同時に変更が必要
• コンポーネントのProps変更：共通コンポーネントのインターフェースを変えると、すべての使用箇所を更新する必要がある
• 設定ファイルの変更：環境変数の追加やデータベース接続設定の変更が、複数の設定ファイルに影響する
• デザインパターンの変更：たとえばクラスベースからフックベースへの移行など、アーキテクチャレベルの変更

これらの変更を手動で行うと、変更漏れが発生しやすく、しかもその漏れがコンパイルエラーにならずにランタイムエラーとして現れる場合は特に厄介です。

Claude Codeが複数ファイル編集で優れている理由

Claude Codeは、プロジェクト全体のコンテキストを理解した上でファイルを編集できるため、以下の点で手動編集やIDEの一括置換よりも優れています。

• 意味を理解した変更：単純な文字列置換ではなく、コードの意味を理解して適切に変更する
• 関連する変更の自動検出：直接の変更箇所だけでなく、波及する間接的な変更も検出できる
• 型定義やテストの同時更新：実装の変更に伴う型定義ファイルやテストコードの更新も同時に行える
• 自然言語での指示：複雑な正規表現を書くことなく、「この関数名をuserDataからuserProfileに変更して、関連するすべてのファイルを更新して」と指示するだけでよい

安全な複数ファイル編集の準備

変更前のブランチ戦略

大規模な変更を行う前に、必ずGitブランチを作成しておきましょう。これが最も基本的かつ重要な安全策です。

# 変更前にブランチを作成
git checkout -b refactor/rename-user-data

# または、Claude Codeに指示する
「作業を始める前に、refactor/rename-user-dataというブランチを作成してください」

ブランチを作成しておけば、万が一変更がうまくいかなかった場合でも、元のブランチに戻るだけで安全にロールバックできます。Claude Codeに直接ブランチの作成を指示することも可能です。

変更範囲の事前調査

大規模変更に着手する前に、影響範囲を把握しておくことが重要です。Claude Codeに以下のように指示しましょう。

getUserData関数の名前をgetUserProfileに変更したいです。
まず変更せずに、この関数が使われているすべてのファイルを
リストアップしてください。

この事前調査により、変更の全体像を把握でき、想定外のファイルへの影響も事前に発見できます。コンテキスト管理の観点からも、影響範囲を先に把握しておくことで、必要なファイルだけを効率的にClaude Codeに読み込ませることができます。

CLAUDE.mdへの変更方針の記載

大規模な変更を複数のセッションにわたって行う場合は、変更方針をCLAUDE.mdに記載しておくと、セッション間で方針が一貫します。

## 現在進行中のリファクタリング
- getUserData → getUserProfile へのリネーム作業中
- 対象ディレクトリ: src/services/, src/components/, src/hooks/
- 完了済み: src/services/
- 未着手: src/components/, src/hooks/

クロスファイルリファクタリングの実践

関数・変数のリネーム

最も頻繁に発生するクロスファイル変更が、関数や変数のリネームです。Claude Codeへの効果的な指示方法を見てみましょう。

src/utils/api.tsにあるfetchUserData関数を
fetchUserProfileにリネームしてください。

以下を含むすべての関連ファイルを更新してください：
1. 関数定義の変更
2. import文の更新
3. 呼び出し箇所の更新
4. 型定義の更新（関連する型名がある場合）
5. テストファイルの更新
6. コメントやJSDocの更新

変更後、TypeScriptの型チェックを実行してエラーがないことを確認してください。

Claude Codeはこの指示を受けて、プロジェクト内の関連ファイルを探索し、すべての参照箇所を更新します。単純な文字列置換ではなく、コードの構造を理解した上での変更なので、同名の別の変数を誤って変更してしまうリスクもありません。

インターフェース・型定義の変更

TypeScriptプロジェクトでは、インターフェースや型定義の変更が広範囲に影響します。

User型にprofileImageUrlフィールド（string | null型）を追加してください。

以下のファイルすべてで対応してください：
1. src/types/user.ts: 型定義の更新
2. src/api/users.ts: APIレスポンスのマッピング更新
3. src/components/UserCard.tsx: 新フィールドの表示追加
4. src/components/UserForm.tsx: 入力フォームの追加
5. src/__tests__/: 関連するテストデータの更新

既存のデータとの後方互換性を保つため、
フィールドはオプショナルとして追加してください。

このように、変更の意図と対象ファイルを明確に指示することで、Claude Codeは整合性を保った変更を実行します。

Import構造の整理

プロジェクトの成長に伴い、import文が乱雑になることがあります。Claude Codeを使えば、プロジェクト全体のimport構造を一括で整理できます。

src/ディレクトリ配下のすべてのTypeScriptファイルで、
import文を以下のルールに従って整理してください：

1. 外部ライブラリのimport（react, next/routerなど）
2. 空行
3. 内部モジュールのimport（@/で始まるパス）
4. 空行
5. 相対パスのimport（./や../で始まるパス）

また、使われていないimportは削除してください。

大規模マイグレーションパターン

段階的マイグレーション戦略

フレームワークのバージョンアップやライブラリの移行など、大規模なマイグレーションは一度にすべてを変更するのではなく、段階的に進めるのが安全です。

以下は、状態管理ライブラリをReduxからZustandに移行する場合の段階的な計画例です。

1. Phase 1：共存環境の構築：Zustandをインストールし、既存のReduxと並行して動作する環境を整える
2. Phase 2：新規機能はZustandで実装：新しく追加する機能はZustandを使用する
3. Phase 3：既存機能の段階的移行：影響範囲の小さいモジュールから順にZustandへ移行する
4. Phase 4：Reduxの完全撤去：すべての移行が完了したらReduxを削除する

Claude Codeには、各フェーズごとにセッションを分けて指示を出しましょう。一度にすべてを実行しようとすると、コンテキストの上限に達しやすくなります。

データベーススキーマの変更に伴うコード修正

データベースのスキーマ変更は、バックエンドのモデル、API、フロントエンドのフォームまで、広範囲に影響します。Claude Codeに以下のような段階的な指示を出すと効果的です。

usersテーブルにdepartment_idカラム（外部キー）を追加する
マイグレーションを作成してください。

合わせて以下のファイルも更新してください：
1. Prismaスキーマの更新
2. User型定義の更新
3. ユーザー作成APIの更新（department_idの受け取り）
4. ユーザー取得APIの更新（departmentのリレーション読み込み）
5. ユーザー一覧画面での部署表示追加
6. ユーザー作成フォームでの部署選択追加

各ファイルの変更は、既存のテストが壊れないように配慮してください。

アトミックな変更を実現するテクニック

アトミック変更とは

アトミック（不可分）な変更とは、複数のファイルへの変更がすべて成功するか、すべて失敗するかのどちらかになる変更のことです。たとえば、インターフェースの定義は変更したが、実装側の変更を忘れた場合、コードは壊れた状態になります。アトミックな変更では、このような中途半端な状態を防ぎます。

Claude Codeでアトミック変更を実現する方法

Claude Codeでアトミックな変更を実現するためのポイントは以下のとおりです。

• 1つのプロンプトで関連する変更をすべて指示する：複数のプロンプトに分けると、途中で方針がずれるリスクがある
• 変更後のバリデーションを含める：「変更後にTypeScriptの型チェックとリントを実行してください」と指示する
• 変更を1つのコミットにまとめる：関連するすべての変更を1つのコミットにすることで、revertも簡単になる

以下の変更をアトミックに実行してください（すべて完了するまでコミットしないでください）：

1. src/types/order.ts: OrderStatus型にCANCELLEDを追加
2. src/api/orders.ts: キャンセルAPIエンドポイントの追加
3. src/services/orderService.ts: キャンセル処理のビジネスロジック追加
4. src/components/OrderDetail.tsx: キャンセルボタンの追加
5. テストの追加・更新

すべての変更が完了したら、型チェックとテストを実行して問題がないことを確認し、
1つのコミットにまとめてください。

ロールバック戦略と安全装置

Gitを使ったロールバック

複数ファイルの変更で最も信頼できるロールバック手段はGitです。変更の規模に応じた戦略を用意しておきましょう。

変更規模	ロールバック方法	コマンド
小規模（数ファイル）	変更の取り消し	git checkout -- [file]
中規模（1コミット）	コミットのrevert	git revert [commit-hash]
大規模（複数コミット）	ブランチ破棄	git checkout main（作業ブランチを破棄）

段階的コミット戦略

大規模変更では、すべてを1つのコミットにまとめるのではなく、論理的な単位で段階的にコミットする戦略も有効です。

以下のリファクタリングを段階的にコミットしてください：

コミット1: 新しいインターフェース定義の追加（既存コードに影響なし）
コミット2: 新しいインターフェースに対応する実装の追加
コミット3: 既存のコードを新しいインターフェースに移行
コミット4: 旧インターフェースの削除とクリーンアップ

各コミット時点でビルドとテストが通ることを確認してください。

この方法なら、途中のコミットで問題が発生しても、影響範囲を最小限に抑えてロールバックできます。

変更のドライラン

Claude Codeに実際の変更を行う前に、変更計画だけを出力させる「ドライラン」を行うのも効果的です。

以下の変更を実際には行わず、変更計画だけを出力してください：
- 変更対象のファイル一覧
- 各ファイルでの具体的な変更内容
- 潜在的なリスクや注意点

UserServiceクラスをUserRepositoryとUserUseCaseに分割したい。

変更計画を確認してから実行に移すことで、予期しない変更が行われるリスクを大幅に低減できます。

複数ファイル編集の実践テクニック集

効果的なプロンプトの書き方

複数ファイルの同時編集をClaude Codeに依頼する際のプロンプトのコツを紹介します。

• 変更の目的を最初に述べる：「なぜ」この変更が必要なのかを伝えることで、Claude Codeが適切な判断を下せる
• 影響範囲を明示する：「src/ディレクトリ配下のすべての.tsxファイルが対象です」のように範囲を明確にする
• 優先順位を付ける：「まず型定義を変更し、次に実装、最後にテストの順で進めてください」と順序を指定する
• 除外条件を伝える：「src/legacy/ディレクトリは変更対象外です」のように、触ってはいけない箇所を明示する

拡張思考モードの活用

複雑な複数ファイル変更では、拡張思考モードを活用しましょう。拡張思考モードでは、Claude Codeがより深くコードの構造を分析し、変更の影響範囲をより正確に把握した上で作業を進めます。特に、依存関係が複雑なケースや、変更の波及効果が読みにくいケースで威力を発揮します。

変更後の検証自動化

複数ファイルの変更後には、必ず以下の検証を行いましょう。Claude Codeに検証も含めて指示することで、自動的に実行してもらえます。

1. TypeScript型チェック：型の整合性が保たれているか確認
2. リントチェック：コーディング規約に違反していないか確認
3. テスト実行：既存のテストがすべてパスするか確認
4. ビルド確認：プロジェクト全体がビルドできるか確認

Hooksを設定しておけば、ファイル保存時に自動でリントやフォーマットが実行されるため、変更後の品質維持がさらに容易になります。

まとめ：大規模変更を恐れずに実行するために

複数ファイルにまたがる大規模変更は、従来は最もリスクの高い作業の一つでした。しかし、Claude Codeを適切に活用することで、安全かつ効率的に実行できるようになります。

本記事のポイントを整理します。

• 事前準備：Gitブランチの作成、影響範囲の事前調査を必ず行う
• 明確な指示：変更対象ファイル、変更内容、除外条件を具体的に指定する
• 段階的実行：大きな変更は段階に分けて進め、各段階で検証する
• アトミック性：関連する変更は1つの論理単位としてまとめ、中途半端な状態を避ける
• ロールバック準備：Gitを活用して、いつでも安全に元に戻せる状態を保つ
• 変更後の検証：型チェック、リント、テスト、ビルドを必ず実行する

これらの原則を守れば、大規模な変更も恐れることなく実行できます。Claude Codeと適切な安全策の組み合わせで、コードベースの継続的な改善を推進していきましょう。リファクタリングガイドやGitワークフローの記事もあわせて参考にしてください。