Windsurfでエラー調査をするときの進め方

Windsurfでエラーを調べるときは、エラーを貼ってすぐ修正させるより、同じ条件で再現し、観察した事実と原因候補を分けてから変更へ進みます。最初に「まだ変更しない」と境界を示し、再現手順・関連file・実行結果を集めるのが安全です。Windsurf Docsの一部は現在Devin Desktop Docsへ転送されているため、CascadeやTerminalの機能名・権限levelは利用中のproductとversionで確認してください。

再現できる情報を一つにまとめる

調査の入口では、エラー文だけでなく、操作やcommand、実際に起きた結果、期待した結果を並べます。ブラウザならURL・操作順・HTTP status・console message、terminalならcommand・exit code・標準出力を揃えます。毎回起きるのか、特定の入力だけかも重要です。

共有する前に、API key、cookie、個人情報、顧客dataを伏せます。secret以外の識別に必要な情報まで消すと原因を追えません。例えば実token値を伏せても、値が空なのか、期限切れなのか、形式不正なのかは残します。production logをそのまま複製せず、必要な行だけ匿名化してください。

再現手順が長い場合は、最小の入力へ絞ります。再現しない状態があるなら、それも記録します。「画面を開くと失敗」ではなく、「ログイン後にSettingsを開き、空の検索欄を送信したときだけ500」と書く方が、call pathを特定しやすくなります。

まず調査だけを依頼する

WindsurfのAIへ最初に求めるのはpatchではなく、観察した条件の再現と原因の切り分けです。例えば次のpromptを使えます。

まだファイルを変更しないでください。次の手順を再現し、失敗する処理までのdata flowを追ってください。原因候補は最大3つにし、各候補について、根拠となるfile・行、確認したlogやtest、候補を否定する条件、次に必要な確認を示してください。再現できなければそのまま報告し、別の操作で推測しないでください。

「根拠file」を要求するのは、単なるfile名の列挙ではなく、どの条件分岐や呼び出しがエラーにつながるかを明らかにするためです。原因が残るなら、次に取るlogや最小testを考えます。候補が多くても、根拠の強さや観測で分けられる条件を整理するまで変更しません。

Contextは必要な範囲を確認する

現行公式Context Awareness資料は、開いているfileに加えてlocal codebaseをindexし、関連snippetをretrievalする仕組みを説明しています。ただし、利用planやenvironmentによって利用範囲が異なります。AIがproject全体を理解している前提にせず、回答内のpathが実際に存在し、現在branchの内容と一致するか確認します。

調査では、対象fileの前後だけで終わらず、呼び出し元、入力を作る箇所、errorを返す場所まで辿ります。修正前に次を確認します。

• 入力値を生成・変換する場所

• validationとerror handling

• 対象functionのcaller

• 同じ処理の既存testとfixture

• environmentやpermissionの違い

• 最近の変更が直接関係するか

Contextを追加するのは、根拠に関係するfileが不足した場合だけです。巨大なdirectoryを一括してpinすると、今回必要な制約が埋もれやすくなります。情報が不足したままなら「不明」とし、欠けたsourceを想像で埋めないようにします。

Terminalで確かめる前に実行権限を確認

Windsurf関連の現行公式Terminal資料は、Cascadeのcommand実行について複数の自動実行levelやallow / deny listを説明しています。またDevin Localでは別のpermission modelを使うとされています。旧Windsurf版やorganization設定では同じUI・挙動とは限らないため、資料上のlevel名をそのまま自分の環境へ当てはめないでください。

commandを実行する場合は、read-onlyな確認とfile変更・外部通信を分けます。調査に必要なcommand、変更が起きるcommand、networkや本番dataへ触れるcommandを区別し、どれを許可するか明示します。実行前に目的と影響を確認し、失敗したcommandを条件を変えずに何度も自動再実行させないでください。

test、lint、buildの出力は仮説を絞る材料です。testが落ちたからといって、エラーと関係のないtestや設定を消してgreenにするのは解決ではありません。実行したcommandと結果を記録し、環境の問題と差分起因の問題を切り分けます。

まずは使ってみる

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

• 

  Windsurf

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

原因が分かってから小さく直す

原因を一つに確定できたら、修正範囲・変えてはいけないcontract・終了条件を指定します。

原因候補のうち、入力validation前にparserが呼ばれるpathが再現testで確認できました。public response、DB schema、dependencyを変えず、validationを先に行う最小変更を提案してください。対象testを追加または更新し、同じ再現手順、正常系、関連checkを実行してください。実行できないものは未確認として分けてください。

これは依頼例で、実際にWindsurf上で実行した記録ではありません。特定APIや実装を保証するものでもありません。実際の原因が別なら、その根拠に合わせて書き換えます。

一回の修正で直らない場合は、追加変更を積み上げず、最初の仮説と新しい観察結果を比較します。新しいerrorが出た場合、最初のerrorの後続症状か独立問題かを分けます。変更前の状態を消さず、diffとtestの対応を確かめてから次の修正へ進みます。

修正後は同じ条件・正常系・境界値を再確認

修正後に「errorが消えた」だけでは十分ではありません。入力が黙って無視されたり、errorが別の形で隠れたりする可能性があるからです。

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

確認	見るもの
同条件で再現	元の操作で同じerrorが消えるか
正常系	正しい入力や操作が引き続き通るか
境界値	空、null、最大値、形式不正など
test	再現testと関連testの結果
diff	原因に関係する最小範囲か
影響先	caller、route、API contractが壊れていないか

元の条件を再現できなかった場合は、修正後にエラーを確認していないと書きます。環境が違うなら、その差を埋めるにはどの情報が必要かを明示します。build成功だけを実画面の正常確認として扱わないでください。

「errorは消えたのに直っていない」を見分ける

次の状態は、修正が成功したように見えても注意が必要です。

• exceptionをcatchして空値を返した

• testを削除またはskipして成功にした

• loggingだけを消して発生条件が残っている

• permission不足を広い権限付与で回避した

• error発生箇所を別functionへ移しただけ

• 不明な入力をすべて同じdefaultへ変換した

• buildだけ成功し、元の操作を再実行していない

これらが必ず誤りとは限りませんが、再現条件・要件・既存contractと照らして判断します。特にerrorを握りつぶした場合は、利用者へのresponseと内部観測の両方で適切かを確認してください。

AIものさしの判断

Windsurfでのerror investigationでは、patchを作る速さより、再現条件・観察・変更範囲が混ざらないことが重要です。最初に読み取りと検証の手順を出させ、根拠のある原因が確定してから最小変更を依頼します。

Terminalの自動実行やagent modeは、製品名やversionだけでなく、現在のpermission設定にも左右されます。公式資料のfeature nameを自分の画面にあると想定せず、実際に利用できる機能と権限を確認します。修正後は、元の再現条件、正常系、境界値、diffを見て、何を確認できたかと未確認事項を分けて記録してください。

調査から修正へ移る判断表

エラーの状態によって、次にすることを切り替えます。

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

状態	次に行うこと	まだしないこと
再現しない	version、入力、環境差を記録して追加観測	原因を決めつけたpatch
複数候補が残る	候補を分ける最小test / logを設計	すべての候補へ同時修正
原因とpathが一致	scopeと合格条件を提示して最小変更	無関係なrefactor
修正後も同じerror	元仮説を見直し、差分と再現を比較	追加patchを連続で重ねる
元errorは消え別error	後続症状か独立問題かを切り分け	まとめて一つの原因と断定

この表の「まだしないこと」は、調査を止める意味ではありません。再現できない場合も、環境や入力の違いを整理すれば次の観測に進めます。productionで起きた問題なら、必要な調査権限や安全なlog取得方法も先に確認します。

変更を続けず止める条件

原因が分かっても、変更にdata loss、permission拡大、外部への送信、schema migration、不可逆操作が伴うなら、修正を始める前に影響と承認条件を整理します。Windsurf系の自動実行設定が高い状態でも、重大な副作用のある操作を自動で進めてよいとは限りません。

一方、変更が小さく、再現testとrollback方法があり、既存contract内で閉じるなら、細かい確認を挟む必要はありません。止まる判断は「実装が難しいか」ではなく「広く・不可逆に影響するか」で行います。