Cursorで複数ファイルをまとめて修正するときの進め方

Cursor Agentへ複数fileの修正を任せるときは、先に変更の目的と境界を固め、plan・file一覧・検証条件を確認してから実装します。Cursorの公式案内では、複数fileや調査を伴う大きな作業にPlan Modeを使い、codebaseを調べてimplementation planを確認する流れが紹介されています。Agentが変更できるfile数に任せるのではなく、diffを人が説明できる単位に保つことが大切です。

まずscopeを表にする

「この機能を直して」だけでは、Agentは関連しそうなUI、API、schema、testへ範囲を広げることがあります。必要な結果と禁止する変更を対にし、許可するdirectoryや対象serviceを明示します。

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

項目	依頼で決めること	例
Goal	利用者に見える完了状態	保存後に一覧へ反映される
Allowed	触ってよい層・file	指定画面とそのunit test
Not allowed	今回変えない仕様	API response、DB schema、URL
Constraints	既存仕様との整合	keyboard操作、権限、error表示
Verification	必須check	test、typecheck、既存build
Stop condition	不確実なら止まる地点	schema変更が必要と判明した時

境界は「触らないfile」だけでなく、既存の意味を変えないことも含みます。たとえばUIの見た目を直すtaskで、APIの型や認証方式を一緒に変える必要が出たなら、実装へ進む前に依存理由を説明させます。

Plan Modeで計画を点検する

大きい変更では、Plan Modeから始め、まずAgentに関連fileと依存関係、考えられる変更順、必要なtestを整理させます。CursorのQuickstartでは、Plan Modeでcodebaseを調査し、詳細planを作ってからbuildへ進む流れを案内しています。planを出したら、すぐ承認するのではなくscope表と照合します。

特に次を確認します。

• 変更候補fileは必要最小限か

• 関係ないdirectoryやgenerated fileが混ざっていないか

• API / schema / permissionの変更を勝手に含めていないか

• testが変更後の挙動を確認できるか

• 失敗時に元へ戻す単位が分かるか

file一覧に意外なpathが出た場合は、理由と読み取った依存元を尋ねます。既存の手元差分をAgentが今回作ったものと混同していないかも開始前後で比べます。planに不明点が残るときは、「実装しながら考える」形へ流さず、先に質問を絞って解決します。

複数fileを論理単位に分ける

変更が複数fileにまたがること自体は問題ではありません。問題になるのは、UI、data migration、認証、APIのように異なるriskを一つの塊へ混ぜて、何が失敗したのか追えなくなることです。変更を責務ごとに分け、各unitでdiffとcheckを確認します。

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

Logical unit	例	先に確認すること
UI + test	form stateと表示	validationと既存design
API + contract test	responseやerror	呼び出し元と互換性
schema migration	field追加や型変更	migration順序とrollback
config	permissionや環境設定	secret、環境ごとの差分
generated output	codegen / static data	generatorと更新理由

UI変更のためにAPIの型を触るなど、unitをまたぐ必要があるなら、planに理由と影響を明示します。migrationやpermissionのように影響の広い変更は、既存project指示に従い別reviewや承認を挟みます。

Agentへ渡す実装brief

Goal：設定画面で選んだ表示名を保存し、再読込後も同じ値を表示する。変更候補は設定画面、既存profile APIの呼び出し元、そのunit testまで。API schema、DB migration、認証、他画面の見た目は変更しない。まず関連fileを示し、既存のsave patternとtest commandを確認してから小さなplanを提示する。保存失敗は既存error UIに合わせる。実装後に変更file一覧、各変更理由、実行したtestと結果を報告する。scopeを守れない依存が判明したら、該当箇所で停止する。

これはbriefの形式例です。実際にはprojectの既存contractやtest名へ置き換えます。change requestに必要なものだけを残し、使っていない制約や架空のfile名を足さないでください。

まずは使ってみる

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

• 

  Cursor

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

Implementation中はcheckpointを見る

一度に多くのfileを変更させると、早い段階の前提違いが最後まで伝播します。大きいtaskは、plan確認、core logic、周辺integration、test・cleanupのようにcheckpointを置きます。各checkpointでは、変更fileとその理由、残りscope、失敗したcheckを並べて確認します。

UI・API・configを同時に変える必要がないなら、実装依頼を分けます。作業を分ける目的は回数を増やすことではなく、異なる責務の差分を独立してreviewできるようにすることです。途中でgenerated fileやunrelated formattingが大量に変わった場合、全部をまとめて受け入れず、generatorの必要性と変更理由を先に特定します。

Testは変更した契約に合わせる

実装が終わったら、既存projectが定めるtest、typecheck、lint、buildのうち、変更内容に対応するものを実行します。複数fileの変更では、unit testだけでなく呼び出し元やintegrationの確認が必要な場合があります。testが失敗したら、Agentに結果を貼って即座に修正させる前に、失敗が今回の変更と関係するか、環境や既存failureかを切り分けます。

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

変更内容	最低限確認するもの
component state	component testと関連interaction
shared helper	helper testと既存call site
API contract	schema / contract test、consumer
routing	route test、internal link
build config	typecheckと対象build
permission	allowed / denied両方の経路

Testが存在しないことを「壊れていない証拠」にしないでください。必要なtestがない場合は、今回のscope内で追加できる最小のcheckを検討します。実行できないcheckは省略理由を記録します。

DiffとGitで戻せる形にする

変更後はfile単位でdiffを読みます。Goalに対応しない変更、関係ないrename、dependency追加、秘密情報、generated fileの予期しない差分があれば、原因を確認します。差分の各部分について「なぜ必要か」「どのtestで確かめたか」を説明できる状態を目指します。

大きく崩れた場合に戻す方法は、Cursor checkpointやGitなど、projectの運用に沿ったものを使います。既存のuncommitted changesを巻き込んでdiscardしないことが重要です。checkpointで戻せると説明されても、その範囲や時点が実際のdiffと一致するか確認します。

AIものさしの判断

複数fileの変更は、Agentの自律性よりscopeの見通しで安全性が決まります。goalと境界を表にし、planとfile一覧を確認し、論理unitごとにdiffとtestを検証します。変更fileが増えたら必ず作業を止めるという話ではなく、変更同士の依存とriskが説明できるかを基準にします。Agentが出す完了報告を、差分・実行結果・contractとの照合で確かめてください。

変更後の引き継ぎメモ

複数fileにまたがる修正では、後から読む人が変更順を再現できるよう、関連fileと責務、主要な判断、実行したcheck、未実施checkを短く残します。とくに移行や段階的変更では、どのstepを先に適用するか、失敗時にどの状態へ戻すかが分からないと、同じ差分でも安全に再実行できません。

Scopeが途中で変わった場合

調査中に新しいdependencyが見つかり、当初の変更境界では対応できないことがあります。そのときは、依存するfileと仕様を示し、何を追加すれば解決できるかを確認してからplanを更新します。黙ってscopeを広げると、後からreviewする人が何を承認したのか分からなくなります。変更の追加が高riskな場合は、低riskの別部分だけ先に完了させず、関連する一連の実装として見直します。