Windsurfで既存プロジェクトを編集する基本手順

Windsurfで既存projectを安全に編集するには、コードを書かせる前に、作業branch・未commit差分・projectのルール・関係fileを把握し、変更範囲と検証方法を決めるのが先です。基本の流れは、理解→小さな変更→実行確認→diff review。現在、旧Windsurf Docsの一部URLはDevin DesktopのDocsへ転送されているため、画面名や機能名は使用中の製品・versionで確認してください。

最初に確認するのはAIより作業場所

既存projectを開いたら、repository rootを間違えていないか、対象branchが合っているか、変更中のfileが残っていないかを確認します。AIが読み込んだ状態を前提にせず、Gitのstatusやdiffを見てから始めてください。別taskの差分が混在していると、AIが今回の変更だと思い込んだり、意図せず上書きしたりします。

作業前に見るものは次の通りです。

• repository rootと現在branch

• uncommitted changesとuntracked files

• README、AGENTS.md、CONTRIBUTINGなどのproject instructions

• package manager、runtime、build / testの標準command

• 変更してはいけないdirectory、generated file、secret設定

• issueや依頼に書かれた受け入れ条件

ルールが食い違う場合は、更新日や適用範囲を比べ、勝手に一つへ統合しません。「repo全体を整理する」と範囲を広げず、依頼されたReader Jobに必要な変更だけを定義します。未commitの変更があるなら、誰の作業か確認するまで編集対象から外してください。

対象に関係する入口だけ調べる

「このprojectを説明して」だけで始めると、一般的な構成の説明に終わることがあります。対象taskに関係する入口を聞き、具体fileの呼び出し関係を確認します。設定画面の文言修正なら、該当route・component・翻訳file・testを探し、どこから表示文言を取っているか追います。目的はproject全体の百科事典を作ることではなく、触る候補と影響範囲を知ることです。

WindsurfのContext Awarenessに関する現行公式資料では、開いているfileに加えてlocal codebaseをindexし、関連snippetをretrievalする仕組みが説明されています。ただし、planや利用環境でindex範囲などが異なるため、対象fileを参照できたかは回答中のpathで確かめます。大きなdirectoryをcontextへ大量に固定せず、必要なfileやinterfaceだけを渡します。

最初にAIへ確認する質問を3つに絞ると進めやすくなります。

1. この変更の入口と、値を処理するfileはどれか

2. 同じ役割を持つ既存実装はどこか

3. 守るべきpublic contractは何か

回答にfile名が並んだだけで理解完了とはしません。既存patternと提案が一致するか、型・test・利用箇所と照らします。見つからないものは「なし」と断定させず、検索した範囲も書かせてください。

planを小さくし、編集前に確認する

複数fileへ触れる変更なら、まず「変更予定file / 各fileの役割 / 変更しないもの / 実行するcheck」を出させます。読むだけの調査と、変更を許可する段階を分けます。scopeが曖昧なままCode系modeへ切り替えると、前提違いのまま編集が進む可能性があります。

小さな依頼なら「既存のボタンと同じpatternでlabelを変更。API、layout、dependencyは変えない。該当unit testを実行」のようにします。大きなtaskでは、変更計画を確認してから、data structure、UI、testのように責務ごとに進めます。最初の回答が違っていたら、実装前に方向を直してください。

現行の公式資料はDevin Desktop内のCascadeにCodeとChat modeを説明しています。Code modeはcodebaseの作成・変更、Chat modeは質問や説明向けです。ただし、旧製品versionや別surfaceにも同じ名称・挙動があるとは断定できません。画面が異なる場合、機能名で権限を想像するのではなく、「まず読むだけ」「承認後にこのfileだけ編集」と操作境界を依頼に書きます。

小さな変更でproject理解を試す

contextが合っているかは、小さくて戻しやすい変更で確認します。copyの修正、局所bug、既存testの追加など、対象と結果が見やすいtaskを選びます。大規模refactorやdependency更新を最初のtaskにしないのは、誤った前提の影響範囲を限定できないからです。

編集後は変更fileと、そのfileを呼び出す境界を説明させます。依頼した変更に見えないformat変更、生成file、全ファイル書き換えが含まれていたら、その理由を先に聞きます。説明が曖昧なら、diffを消す前に、どの変更が自分の作業に属するかを確認します。

複数人や別sessionで同じprojectを編集する場合、checkpointはGitの代わりではありません。現行公式資料ではCascadeがcheckpointを用意しますが、revertは不可逆と説明されています。操作前にdiffやcommitなど別の復元手段を確認してください。同じfileの並行編集は競合しやすいため、必要なら別branchやworktreeに分けます。

まずは使ってみる

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

• 

  Windsurf

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

project contextを渡すprompt例

目的・入口・制約・検証を分けると、どこまで任せるか伝わります。

目的：設定画面の保存後に成功表示を出す。

まず変更せず、該当route、form、API、関連testを調べてください。既存の保存方法と似た画面も確認し、変更候補fileとdata flowを説明してください。

制約：公開APIのresponse、database schema、他画面の挙動、dependencyは変えません。未commit変更は保持し、無関係なfileには触れないでください。

調査結果を確認したあと、指定範囲だけ編集してください。

完了条件：成功時は既存のsuccess patternで表示し、validation error時は入力が消えない。関連testを実行し、commandと結果、未実行の確認を分けて報告してください。

これは依頼の組み立て例で、特定projectで検証済みの指示ではありません。routeやfieldは自分のprojectのものへ置き換えます。既存structureが分からない段階で「このrouteを実装して」と決めず、候補を調べてから作業範囲を確認してください。

検証はprojectの標準手順を使う

変更後に実行するものは、package.json、README、CI、既存testから確認します。AIにcommandを想像させないでください。標準testが重い場合は、対象unit testやtypecheckを先に実行し、必要な全体checkへ進みます。

結果は「実行した」「失敗した」「この環境では実行できない」を分けます。buildが通っても、変更した画面の動作確認をしたことにはなりません。UIなら画面を開き、入力・保存・遷移など対象操作を確認します。APIならresponse shape、status code、既存consumerを見ます。

testがない場合、AIの説明だけで既存処理が正しいと宣言させず、testか確認可能な手動手順を残します。検証commandを提案させた場合も、そのscriptが実際に存在するか確認します。testを新規作成するなら、既存runnerとassertion styleを使い、期待値が要件に沿うかレビューします。

diffを見て、範囲が広がったら戻る

要約だけでなく、実際のdiffをfile単位で見ます。各変更について「依頼との関係」「追加した条件」「削除した処理」「副作用」を確認します。shared utilityを変えたら他のcallerが変わる可能性があるため、利用箇所と必要なtest範囲を確かめます。

次の兆候があれば、そのまま採用せず範囲を再調査します。

• 要件にないfileが増えている

• APIやDB contractが説明なく変わっている

• 既存testを削除・弱体化している

• errorを握りつぶすなど症状を隠している

• dependencyや環境設定が理由なく変わっている

• 「すべて成功」と報告するが実行記録がない

• generated outputの大幅変更が説明されていない

作業が想定より広がったら、どの変更が必須かを再確認します。追加変更が必要なら理由・影響・checkをscopeへ含めます。不要なら分けて後回しにしてください。

AIものさしの判断

既存projectの編集では、AIが何file読んだかより、変更前に影響範囲とcontractが共有されているかが重要です。branch・差分・rules・標準commandを確認し、計画をreviewしてから小さな編集へ進みます。

普段の小さな修正なら調査と変更を一度に頼んでもよいでしょう。ただし、未commit変更が多い、対象が曖昧、API・data・permissionに触れる、戻しにくいといった条件があれば、調査→計画→編集に分けます。UI名やversion依存のfeature名に頼りすぎず、どの範囲を読んで何を許可するかで調整してください。

AIから「完了」と言われた時点で終わりにせず、受け入れ条件に対応したcheckを確認します。作業開始前に見るもの、AIへ渡すprompt、変更後に確かめるdiff・testが揃えば、読者は安全に既存projectの編集を開始できます。

現行の公式案内はDevin DesktopとWindsurf Pluginsに分かれています。画面名やCascadeの操作を参照するときは、まず使っているアプリ名とversionを確認し、旧Editor向けの手順をPlugin側へそのまま当てはめないようにします。