Windsurf 把寫 code 變成代理編輯

我拆 Windsurf 的 agentic IDE 思路，順手給你一份能直接抄進真實 codebase 的 Cascade 工作流。

我用 AI 寫 code 用到現在，最怕的不是它不會寫，是它太會點頭。你丟一句需求，它回你「好啊」。你說改方向，它也說「可以」。看起來很乖，實際上常常只是把我本來就要做的判斷，包成一坨更大的待辦。Windsurf 一開始給我的感覺也差不多，什麼 agentic IDE、Cascade、多檔案編輯、終端機執行，聽起來很滿，但我心裡第一個反應是：又來一個把 autocomplete 包裝成助理的工具吧。

後來我去看 AI Wiki 的 Windsurf 頁面，才發現它不是想裝成聊天框，而是想把編輯器直接做成能動手的工作台。這個差很多。因為我真正煩的，從來不是「它能不能回答」，而是它能不能少讓我在檔案、終端機、測試結果之間來回跳。這篇我就拆這個想法，順便把我會怎麼用 Cascade 寫成一份可直接抄的版本。

Windsurf 不是聊天框，是把你從搬運工變回工程師

Launched in November 2024, Windsurf positions itself as the first "agentic IDE," combining traditional code editing with an AI agent called Cascade that can understand entire codebases, perform multi-file edits, and execute terminal commands ...

這句話我翻白話就是：它不想只幫你補幾行字，它想把「看 code、改 code、跑驗證」這三件事塞進同一個流程裡。這才是重點。因為真正耗時間的，從來不是那幾行 patch，而是 patch 之後一堆連帶工作：找相關檔案、補測試、跑指令、看失敗、再回頭修。

我以前最常卡住的，就是工具很會答，但不會接著做。你問它怎麼改，它給你一段漂亮說明；你要它真的動手，它又開始只改當下那個檔案，然後把後果留給你。這種工具我用久了只會更累，因為我等於多了一個會講話但不會收尾的實習生。

Windsurf 的野心比較務實：它要把「編輯器」變成一個能接住上下文、能跨檔案協調、能跑驗證的工作環境。這不代表它真的懂整個 repo，老實說沒有模型真的會像人一樣懂一個亂七八糟的專案；但只要它能看到更多相關檔案、保留更多脈絡、少讓我手動搬東西，它就已經比很多只會在單一游標旁邊講幹話的工具有用。

我自己在 monorepo 做過一個功能，牽到 UI component、shared util、還有 test。傳統 chat 助手最愛做的事，就是只改你眼前那個檔案，然後裝沒看到其他地方。結果我還是得自己追 import、追測試、追行為差異。那種體驗很像你請人幫忙搬家，結果他只幫你把箱子貼上標籤。

實操上，我會把 Windsurf 放在「牽涉範圍明確但不是單點修改」的任務上。像重構、API rename、測試同步更新、功能串接，這些都適合。只有一行的小修正，我不會故意開 agent，因為那是在浪費工具的協調能力，也是在浪費我的注意力。

• 適合：跨檔案重構、符號改名、測試同步、功能串接。
• 不適合：明顯只有一行的修補、我已經知道答案的修改。
• 原則：讓工具處理搬運，我只負責判斷對不對。

Cascade 的價值，不是會聊，是會把事情收完

Cascade 是 Windsurf 真正的核心。AI Wiki 明講它可以做多檔案編輯，還能執行終端機命令；Windsurf 官方網站也把它放在產品敘事中心。Windsurf 官網 這種寫法其實很直白：它不是要你把 editor 當聊天視窗，而是把 agent 放進編輯器裡，讓它從修改一路做到驗證。

白話一點說，Cascade 不是只會生 code，它還能把 code 送去跑。這個差別超大。因為我最煩的不是寫完，是寫完之後那串瑣事：裝依賴、跑測試、看 build、抓錯誤訊息、再回頭修。很多 AI coding 工具卡在這裡，因為它們只負責「生成」，不負責「收尾」。

我之前遇過一個情境，模型把 function 改對了八成，卻漏掉一個 test expectation。假如工具只能吐字，我就得自己切到 terminal，自己跑，自己看錯誤，自己再回來改。這種來回切換是最耗精神的。若 agent 能直接跑驗證命令，至少它可以把失敗提早攤開，不要讓我晚十分鐘才發現整包都歪了。

但我也不會天真到把 terminal 權限當成加分就全開。這東西的風險很直接：它不只可以幫你跑測試，也可以幫你亂跑命令。所以我的做法一直都很保守。先改碼，再驗證，再看 diff。不要讓它自由發揮，更不要讓它在沒審過的情況下碰破壞性指令。

實操寫法很簡單：每次都先把驗證命令講清楚。你要它跑測試就講測試，要它跑 build 就講 build。不要丟一句「幫我修好」然後期待它自己知道該怎麼收尾。Agent 不是通靈，它只是比較會做事。

• 先定義驗證命令，再讓它改。
• 優先用「改碼 → 跑驗證 → 看結果」的循環。
• 危險命令不要默認放行，尤其是 migration、deploy 這類。

Repo-aware 不是更聰明，是比較少瞎猜

很多 AI coding 工具都愛講自己更聰明，但我其實不太吃這套。對我來說，真正有差的是它有沒有 repo awareness。也就是說，它是不是知道這個專案裡哪些檔案彼此有關，哪些地方改了會連動，哪些測試會一起炸。這種能力不華麗，但很值錢。

翻譯一下就是：它不只看游標附近那一小塊，而是能把整個專案的結構拿來當參考。這對真實 codebase 很重要，因為真實 codebase 從來不乾淨。你改一個 hook，component 會跟著變；你改一個 type，test fixture 會跟著壞；你改一個 config，可能連 CI 都要補。這些關係如果工具看不到，它就只會產出看起來合理、實際上很危險的建議。

我在前端專案裡最常遇到這種事。你以為只是在 component 裡換個 prop 名稱，結果還有 story、test、mock data、甚至某個共用 helper 要一起動。只看單檔的助手會一直裝作事情很單純，然後把清理工作留給我。repo-aware 的價值就在這裡：它至少有機會把相關面一起抓出來。

但我還是要講難聽一點：它能找出相關檔案，不代表它就真的懂架構。所以我不會讓它靠感覺亂改。我會要求它先列出它認為相關的檔案，講清楚為什麼，然後再動手。這樣我可以先擋掉一半瞎猜，避免它把錯誤擴散到更多地方。

實操上，你下指令時要把影響範圍講完整。不要說「幫我改登入流程」，要說「改 hook、consumer component、相關 test，順便確認 type 沒壞」。你越具體，它越少亂飄。

• 先點名受影響的檔案層級，不要只講功能名。
• 要求它先列相關檔案，再進行修改。
• 把「可能連動的測試」也一起講進去。

多檔案編輯有用，但前提是你會看 diff

多檔案編輯這件事很容易被講得很神，好像只要工具會一次改很多檔，就代表它很厲害。不是。它只是把機械性搬運做得比較快而已。真正值錢的是，它能不能在你不想手動複製貼上時，幫你把連動的修改先鋪好。

我自己的經驗是，這種功能最適合做符號改名、refactor、測試同步、設定檔調整。這些工作有一個共同點：它們的變動規則很機械。只要規則清楚，agent 就很適合接手。可是一旦牽涉到語意判斷，你就不能只看它改了幾個檔案，還要看它有沒有真的保住行為。

我以前被一個助手搞過一次。它把 implementation 改了，也把 test 名稱改了，看起來整齊到不行，結果漏掉一個 assertion 還在驗證舊邏輯。那種 diff 很有欺騙性，表面上像整理過，實際上只是把錯誤包得更漂亮。所以我現在看多檔案修改，一律當草稿，不當答案。

這裡的實操方法其實很土，但有效：讓 agent 做機械搬運，然後你自己看 diff。不要只看總結，要一檔一檔看。尤其是它額外碰了你沒點名的檔案時，先問原因，不要先按接受。

如果你要我講一句最實際的原則，就是：多檔案編輯能省時間，但前提是你把省下來的時間拿去做 review，不是拿去偷懶。

• 把多檔案編輯當 draft generator，不要當 authority。
• 逐檔 review，不要只看一坨總 diff。
• 每次都跑你原本會跑的驗證指令。

終端機權限讓它像真的在做事，但也更需要你設界線

Windsurf 讓 Cascade 能跑 terminal commands，這就是它跟很多 AI 編輯器拉開差距的地方。因為一旦它能跑命令，它就不只是「建議你怎麼做」，而是可以直接參與開發流程。這個差別很實際，尤其是在你已經快被上下文切換搞瘋的時候。

白話講，這代表它可以幫你跑 install、test、build，甚至把錯誤訊息帶回來。對我來說，這是最像「真的有幫上忙」的部分。因為我不想一邊盯 code，一邊還要手動切到 terminal 找錯。能把這段交給 agent，至少我比較能專心看它改得對不對。

但我也不會把這件事浪漫化。terminal 權限不是免費午餐，是風險放大器。它如果只是在 code 層面犯錯，你還能靠 review 擋住；它如果開始亂跑命令，事情就會變得更麻煩。所以我對這種工具的期待一直都很明確：它可以快，但不能自己亂決定。

我的做法是先訂 command policy。哪些能跑、哪些不能跑，先寫死。測試和 build 可以，migration、deploy、刪資料這種不行。然後把常用驗證命令固定下來，避免每次都重新討論。這樣 agent 才不會把你的環境當實驗場。

如果你想找類似的工作流對照，我會順手看 Visual Studio Code 的擴充方式、GitHub Copilot 的定位，還有 Cursor 怎麼講 repo-aware editing。這幾個都能幫你看清楚 Windsurf 到底在賣什麼。

我對 agentic IDE 的底線很簡單：保留意圖，檢查成果

很多人用這類工具會犯一個錯：把 agent 當成替代判斷的人。這很危險，也很沒效率。比較合理的期待是，它幫你減少機械成本，讓你少做那些重複搬運、重複追檔案、重複跑命令的事。判斷還是你做，工具只是幫你把路鋪平一點。

也就是說，你要的是 workflow，不是神諭。先丟清楚任務，讓它跨檔案修改，跑驗證，然後你自己看 diff。這才是 agentic IDE 真正有價值的地方。太鬆，它會亂飄；太緊，它就退化回昂貴的 autocomplete。

我現在最喜歡的用法其實很無聊：任務寫得很具體，範圍寫得很明確，驗證命令寫得很死。像「把這個 API field 改名，連 test 一起更新，然後跑 test suite」。這種 prompt 不性感，但它有效。因為模型最怕的不是難題，是你講話像在許願。

如果你也想把 Windsurf 或類似工具用得像樣，我建議你先把「人要做什麼、agent 要做什麼」切開。人負責定義，agent 負責搬運和驗證。這樣你才不會每次都在等它自作聰明。

可抄的模板

# Windsurf / Cascade 工作流模板：把 agent 變成可控的改碼助手

## 任務定義
- 目標：一句話講清楚我要達成什麼結果
- 範圍：列出檔案、資料夾、module、symbol
- 約束：哪些東西不能改，哪些行為不能變
- 驗證：要跑的 test / build / lint 指令

## 丟給 agent 的 prompt
你現在在我的 codebase 裡工作。

先找出跟這個任務相關的檔案，並簡短說明為什麼它們相關。
接著只做達成目標所需的最小修改。
修改完成後，請執行我指定的驗證命令，並回報結果。

規則：
- 不要改與任務無關的程式碼。
- 不要用猜的方式補架構，除非 repo 已經明確有既有模式。
- 如果測試失敗，先解釋失敗原因，再繼續改。
- 保持 diff 簡單、可 review。
- 若需要新增檔案，先說明新增原因。

## 範例任務
目標：把 billing flow 裡的 `userId` 改成 `accountId`
範圍：`src/billing`、相關 tests、shared types
約束：不要改 API response shape
驗證：`npm test -- billing`

## Review checklist
- [ ] 受影響的檔案都更新到了
- [ ] import / export 還能正常解析
- [ ] tests 已反映新行為
- [ ] 驗證命令有跑完
- [ ] 沒有夾帶無關重構

## 追問模板
先給我 diff summary，再告訴我你額外改了哪些我沒點名的檔案，以及原因。

這段就是我會真的存下來的版本。它把 agent 卡在一個很窄的 lane：先列相關檔案，再做最小修改，再跑驗證，最後把額外變動交代清楚。這樣用，Windsurf 才像工具；不這樣用，它就只是會講話的麻煩製造機。

來源致謝：核心觀點來自 AI Wiki 的 Windsurf 頁面，以及 Windsurf 官網。上面這套 workflow 與模板是我根據來源內容整理、再加上自己的實戰習慣改寫出來的。