Claude Codeで複数ファイルを変更するときの進め方

Claude Codeで複数fileを変更するときは、対象を数えるより「どの責務をどの順番で変え、何を確認したら次へ進むか」を先に決めます。UI、data flow、API、testをまとめて一度に変更すると、途中で仕様がずれたとき原因を分けにくくなります。必要なfileを根拠と一緒に特定し、論理単位ごとに編集と検証を繰り返します。

AnthropicのCommon workflowsは、コード編集前にplanを確認する方法と、変更を小さくしてtestで確かめる例を案内しています。複数sessionをworktreeで分ける機能もありますが、並列化は作業の衝突や統合負担を増やすため、常に速くなるとは限りません。まず単一の作業列で完了できるか考え、独立して並行できる変更だけを分けます。

変更範囲を「目的・制約・完了条件」に分ける

最初に目的、維持する契約、変更禁止範囲、検証条件を書きます。「複数fileを直す」だけでは、どこまで変えてよいか分かりません。たとえばAPI responseの形を維持する必要があるなら、その条件を明示します。

表は横にスクロールできます

項目	例	確認方法
目的	保存時に入力を検証する	invalid / valid inputのtest
維持する契約	response schemaと既存route	呼び出し元とsnapshot確認
変更対象	handler、validation helper、test	planのfile一覧
変更禁止	public type、migration、unrelated refactor	diff review
完了条件	unit testとtypecheckが通る	command result

Claude Codeには、まずrepositoryを読んで候補fileと依存関係を説明させます。ファイル名から役割を決めつけず、import元、呼び出し元、test、configurationをたどらせます。ここで見つかったfileが正しいかは、人がsource codeの経路と照らして確認します。

実装前に、今回の目的に関係するfileとそれぞれの責務を表にしてください。変更範囲、維持する既存behavior、必要なtestを示してください。まだ編集せず、別のfeatureや既存WIPに触れる必要があるなら理由を出してください。

Planをfile一覧から変更順へ変える

Planは「A.tsを変更、B.tsを変更」という一覧だけでは足りません。どの契約を先に定義し、どの変更を次に接続し、どのtestで検証するかを順番で示します。上流のdata contractや型変更が下流へ波及する場合、順序を逆にしません。

表は横にスクロールできます

順序	作業単位	確認point
1	現行behaviorと再現testを確認	変更前のbaselineを記録
2	shared contract / typeを必要最小限変更	consumerと互換性を確認
3	production実装を変更	変更理由をfileごとに記録
4	unit / integration testを追加・実行	正常、境界、failure path
5	関連route / buildを確認	変更範囲と生成差を確認
6	diffを整理	無関係な変更が0

この順序は雛形であり、すべての記事へ同じ工程を当てはめるものではありません。UIだけの修正ならschemaやmigrationのstepは不要です。契約変更を伴う場合は、downstream consumerを先に洗い出し、互換性が確認できない箇所を計画に残します。

fileを分ける単位は責務と検証しやすさ

一つの変更単位に複数fileが含まれてもかまいません。たとえばcomponentとそのtestは一緒に変える意味があります。一方、認証設定、見た目のpolish、data migrationを一つのcommitへ混ぜる理由は薄いでしょう。

変更単位を決めるときは、以下を使います。

• その単位だけで意図を説明できるか

• 変更前後のbehaviorをtestで確認できるか

• 失敗時にどの単位を戻すべきか分かるか

• 他の作業がその結果に依存しているか

• 既存のpublic interfaceを変えるか

たとえばform修正なら、validation rule、API handler、UI error表示、testのように契約をつなぐ範囲で分けます。単にdirectoryごとに分けるのではなく、ユーザーが送信した値がどこで判断されるかを追えるかで区切ります。

同じbranchで順に変更するときのcheckpoint

複数単位を順に進める場合、各checkpointでdiffと関連testを見ます。Claude Codeへ「全部実装して最後に知らせて」と頼むと、中間の前提違いが積み上がります。作業単位ごとに次を受け取ります。

1. 変更fileと変更目的

2. test・buildなど実行結果

3. まだ満たしていない条件

4. 次の単位へ進む前に必要な判断

5. 予想外の変更や既存failure

checkpointはreviewのためであり、毎回branchをcommitする指示ではありません。commitやmergeのルールはrepository固有の運用に従います。要求に含まれないdeployやdata更新は、この作業と分離します。

まずは使ってみる

記事の文脈に合うToolへ進めます。報酬の有無で見た目は変えていません。

• 

  Claude Code

  公式サイトを見るTool詳細を見る比較を見る

並列作業を使うのは互いに独立した範囲

Anthropicの公式workflowにはGit worktreeを用いたparallel sessionの案内があります。worktreeは別checkoutとして作業を分離する仕組みですが、同じfile、共有schema、同じ生成artifactを複数sessionが触る場合は衝突し得ます。作業開始前にbase commit、branch、変更対象、統合責任者を確認します。

並列化しやすいのは、たとえば別々の独立した調査・documentation・isolated packageの修正です。共通typeの変更、同一componentの修正、依存するAPIとclient変更は、順番に進める方が安全です。別worktreeに移動しただけでは、双方の実装が統合できる保証にはなりません。

並列作業の依頼では、共有する契約と編集禁止fileを伝えます。結果を取り込む前に、branch間diff、conflict、test、generated fileの再現性を確認します。worktreeやsubagentが使えない環境なら、同じ目的を小分けにした順次作業へ切り替えます。

testは変更単位の契約に合わせる

変更したfile数とtest数を一致させる必要はありません。testは変更対象の数ではなく、守るべきbehaviorとfailure pathに対応させます。

表は横にスクロールできます

変更	例となる確認
入力validation	空、境界値、型違い、正常値
API response	status、schema、error時のbody
data mapper	未知値、欠損、複数row、重複
UI	初期状態、操作後、error、mobile
shared type	すべての主要consumer、build
file output	生成件数、hash、routeの重複

testが失敗したら、どの単位で初めてfailureが現れたかを見ます。Testをskipしたりassertionを弱めたりする前に、productの期待とtest自体が合っているかを照合します。実行時間を節約するために一部のcheckだけ行った場合、全suiteまで成功したように報告しません。

Claude Codeへ渡す実装brief

目的：［user behavior］

変更してよい範囲：［file / package］

維持するcontract：［URL、API、data semantics等］

変更禁止：［schema、secret、unrelated WIP等］

まず調査：関連file、依存関係、baseline test

実装単位：［順番とcheckpoint］

各stepのQA：［具体的なtestと期待結果］

想定外の影響が分かった場合：編集を止め、変更範囲と理由を示す

このbriefでは、ユーザー要件を実装taskへ変換しつつ、各stepで何を検証したかを残します。秘密情報や実dataはpromptへコピーせず、必要ならsample fixtureを使います。

予定を更新する条件

計画中に新しい依存が見つかった場合は、当初のfile一覧に無理に押し込みません。影響が小さく、既存contract内で直せるなら最小限追加し、原因と検証を記録します。新しいschema、外部data、公開API、permission、multi-package architectureへ広がるなら、依存とリスクを出してそこで止まります。

後から「ついでにformatを統一する」「別moduleもrefactorする」といった要望を混ぜると、最初の修正の成功判定が曖昧になります。別のtaskとして分け、同じcommitへ入れる必要が本当にあるかを考えます。

AIものさしの判断

Claude Codeの複数file変更では、編集能力ではなく範囲・順序・検証が結果を左右します。目的と維持する契約を固定し、fileの責務に沿って変更単位を切り、testが通った範囲をcheckpointとして積みます。並列化は独立した変更だけに使い、最後に統合後のdiffと全体確認を行います。作業範囲やsource of truthが変わったときは、旧計画を続けずに影響を整理してから進めてください。