Windsurfで複数ファイルを修正するときの使い方

Windsurfで複数ファイルをまとめて修正する場合は、最初に「完成させたいこと」と「編集してよい範囲」を分け、候補fileと依存関係を確認してから、小さな変更単位に進めます。複数fileを一度に触ること自体より、共通contractを見落としたまま編集を広げることが失敗の原因です。旧Windsurf Docsの一部は現行のDevin Desktop Docsへ転送されているため、利用中のproduct / versionを確認し、画面名や機能名を固定しすぎないようにします。

先に完成条件を一文にする

「ログイン機能を改善」では、何をどう改善するのか判断できません。「期限切れtokenならrefresh endpointを一度だけ呼び、失敗時はログイン画面へ戻す。既存API responseは変更しない」のように、入力・出力と守る条件を明確にします。

次に、編集対象と禁止範囲を分けます。画面、API handler、testは候補でも、DB schemaや依存libraryは変更禁止かもしれません。許可されていない範囲をAIが補ってよいことにはしません。生成code、lockfile、format全体の変更が必要なら、その理由を先に出させます。

編集前にfile mapを作る

実装前に、関係fileの役割とdata flowを確認します。例としてプロフィール保存なら、入力→validation→API request→server handler→保存→response→画面表示を並べ、今回どこが変更範囲かを見るのが有効です。

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

層	探すもの	変更前に確認すること
UI	page、form、shared component	入力と状態をどこで持つか
API	endpoint、client、server handler	request / response contract
data	schema、repository、query	schema変更が本当に必要か
tests	unit、integration、fixture	同じ挙動をどう検証するか
docs / config	rules、environment、scripts	既存手順に従えるか

この表は全層を必ず変更する意味ではありません。存在する層を把握し、不要な変更を避けるための調査表です。無関係な層はscopeから外します。AIに「まず読み取りだけで、entry point、関係file、data flow、public contract、testを列挙。変更案はその後」と頼み、file mapの各行に根拠pathを添えてもらいます。

変更単位は責務と失敗境界で切る

UI、API、data、testを一度に編集するより、依存順に小さな段階へ分けると原因を追いやすくなります。先にcontractやvalidationを決め、次に処理本体、その後にUI表示とtestを更新するなど、何を確認して次へ進むかを明示します。

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

段階	作業例	次へ進む条件
調査	call path、既存pattern、影響caller	前提とscopeを確認済み
contract	request、response、error condition	既存consumerと互換
実装	関係fileだけを更新	diffが予定範囲内
検証	test、typecheck、build	failureの原因を説明可能
仕上げ	UI、docs、generated file	各変更が要件に結びつく

すべてのtaskで五段階が必要とは限りません。小さな二file修正なら一度に進めてもよい一方、schemaやpublic APIを変えるなら境界を分けます。作業量よりも、失敗時にどこで止めて原因を特定できるかで粒度を選びます。

contextは必要なfileへ絞る

複数file編集では、実装、型、rule、testが一緒に必要になります。しかしrepository全体を会話へ貼ると、関係の薄い情報が増え、重要な制約が埋もれます。現行公式資料はcodebase indexing / retrievalと必要contextのpinningを案内しています。一方、indexingやpinned contextの上限はplan・environmentで違うため、実際に参照できたfileを回答で確認します。

contextを選ぶ順序は次の通りです。

• 対象fileと直接caller

• 同じpatternの既存実装

• 型、interface、API contract

• 対象testとfixture

• repository instructionsと安全制約

pinしたcontextは固定し続けず、taskが変わったら不要fileを外します。前提が古いとAIは一貫して誤った変更を作ることがあります。参照元のbranchや更新日、current worktreeの内容かも確認してください。

まずは使ってみる

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

• 

  Windsurf

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

Scopeを渡すpromptの例

目的：設定画面で名前変更を保存できるようにする。

まず読み取りだけで、画面、request client、server handler、validation、関連testを探し、data flowと変更候補fileを示してください。

制約：DB schema、既存response shape、他画面の挙動、dependencyは変更しない。未commit差分も変更しない。

実装はcontract、画面、testなど責務ごとに進め、各段階でdiffを確認してください。

完了条件：保存成功表示、空文字と長すぎる入力のvalidation、関連testが確認できる。実行commandと結果、未実行の確認を分けて報告してください。

これはpromptの組み立て例で、特定projectで検証した指示ではありません。routeやfieldを自分のprojectに置き換えます。追加要件の影響が広い場合、AIが仕様を補って進めるのではなく、既存contractの確認を挟みます。

Test範囲はfile数では決めない

2fileだけでもshared utilityなら多数画面へ影響することがあります。逆に5fileでも一つの画面内で閉じることがあります。検証範囲はdiffの数ではなくdata flowとcallerで決めます。

• 変更対象のtestまたは最小再現test

• 正常系と代表的なboundary value

• 型・lintなどrepository標準check

• API contractを触ったなら既存client / consumer

• UIならempty・loading・success・error状態

• generated fileなら再生成結果との一致

テストがないからといって、AIの説明だけで正しさを宣言させません。testを加えるか、再現できる手動手順を残します。buildに時間がかかるなら局所testを先に実行し、必要な全体checkへ進みます。今回差分が原因か既存failureかも分けて記録します。

diffとcheckpointを使い分ける

要約だけではなくdiffをfile単位で見て、各変更が目的・必要test・contractとどう関係するか確かめます。shared component、型定義、package設定、generated fileは、一つの画面を越えて影響する可能性があります。

現行の公式Cascade資料はcheckpointによるrevertを説明していますが、revert自体が不可逆とされています。checkpointを唯一の復旧方法にせず、Git diffやcommitなど別の復元経路を残します。別sessionが同じbranchやfileを編集しているなら、必要に応じてbranchやworktreeを分けて競合を避けます。

scopeが広がったときは、最初に変更候補fileを再確認します。「ついでに直す」変更が必要なら、その理由と追加checkをscopeへ明示します。要件に結びつけられない変更は今回から外してください。

失敗を早く見つける確認表

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

兆候	考えられる問題	次の確認
API responseも変わった	contract変更が混入	callerと既存仕様を確認
予定外のfileが増えた	scopeの拡大	各fileの必要性を照合
testを削除してgreen	gateを弱めた可能性	削除理由と代替test
errorを一括で握りつぶす	原因を隠している	個別failure path
lockfileが大幅変更	dependency更新	必要性とversion
「check済み」だが記録なし	未実行の可能性	commandとexit code

異常があっても差分をすぐ捨てず、どの段階でscopeを越えたかを特定します。一部だけ戻すときは、他の未commit作業を壊さないよう、変更の所有者と現在の状態を確認してください。

AIものさしの判断

複数file編集では「一度に多く直せる」ことより、共通contractと変更境界を見失わないことが大切です。目的を入力・出力へ落とし、file mapからscopeを決め、責務ごとに編集します。

小さい変更単位は必ず一fileずつという意味ではありません。UIとそのtestのように密接な変更は同時に扱えます。重要なのは、各単位に受け入れ条件があり、失敗時に原因と影響範囲を説明できることです。

読者が作業を開始できる状態は、対象file、守るcontract、実施するcheck、diffのreview観点が手元にあることです。完了後に「なぜこのfileを変えたのか」「何を実行したのか」に答えられないなら、完了扱いにしないでください。

複数fileを扱う前に、利用中の画面がDevin DesktopかWindsurf Pluginかを確認してください。現行の公式案内は両者で分かれており、CascadeのCode modeや画面操作は同じ前提とは限りません。この記事の作業分割は共通の考え方として使い、固有のUI手順は該当アプリの現行docsで照合します。