從原理到實戰
第一次專案閉環
用只讀理解、單檔案修改、驗證命令和 diff 檢查四步，把 Windsurf 安全放進真實專案。
第一次用 Windsurf，不要讓 Cascade “重構整個專案”。正確目標是跑通一個低風險閉環：只讀理解專案，限定單檔案修改，執行最小驗證，檢查 diff，然後決定繼續、回復或提交。
本篇目標：讓你用真實專案完成第一輪安全驗證，而不是隻在 demo 裡點按鈕。
1. 選擇練習專案
練習專案要真實，但不能高風險。
適合：
- 有 git。
- 有清晰目錄結構。
- 有 lint、test 或 build 命令。
- 你知道大概功能範圍。
- 當前分支不是釋出前凍結分支。
不適合：
- 含生產金鑰、客戶資料或未脫敏日誌。
- 沒有版本控制。
- 大量生成物沒有被
.gitignore/.codeiumignore排除。 - 正在多人併發大改。
- 一旦誤改就會影響生產後臺、支付、部署或資料庫。
正式開始前先做本地檢查：
git status --short
git branch --show-current如果已有未提交改動，先確認哪些是你自己的、哪些是別人或其他 agent 的。不要讓 Cascade 在髒工作樹裡無邊界修改。
2. 第一步：只讀理解
第一條訊息必須明確“只讀”：
先只读分析这个项目，不要修改文件，不要执行命令。
请输出：
1. 技术栈
2. 主要目录职责
3. 入口文件
4. 测试和构建命令线索
5. 你认为最需要先读的 5 个文件你要檢查它是否準確識別：
- 框架和語言。
- package / config / route / app 入口。
- 測試、lint、build 命令。
- 專案規則檔案，例如
AGENTS.md、.windsurf/rules/、README。 - 不應讀取的路徑。
如果它一開始讀錯方向，先糾正上下文，不要進入修改。
3. 第二步：限定單檔案修改
選擇一個低風險任務：
- 改文案。
- 修 typo。
- 給錯誤提示補上下文。
- 給 README 補一行說明。
- 給小函式補一個明顯缺失的 guard。
提示詞：
只修改这个文件：src/components/example.tsx。
目标：把空状态文案改得更具体。
不要修改其他文件。
不要运行命令。
修改后说明你改了哪几行、为什么改。觀察 3 件事：
- 是否只改目標檔案。
- 是否解釋了修改理由。
- 是否主動擴大範圍、順手重構或格式化無關內容。
如果它越界，立即停下，讓它解釋為什麼改了其他檔案，並用 git diff 自己判斷是否回退。
4. 第三步：先列驗證命令
不要讓 Cascade 直接跑它想到的所有命令。先讓它列出最小驗證集：
请列出验证这个改动最小需要运行的命令。
先不要执行。
每条命令说明目的和风险。低風險命令通常包括：
git diff --stat
git diff
pnpm lint
pnpm test
pnpm run build但命令必須以專案事實為準。沒有 pnpm 就不要硬跑 pnpm；沒有測試指令碼就先讀 package.json、README 或 CI 配置。
5. 第四步：檢查 diff
閉環的最後一步不是“測試透過”，而是你看過 diff：
git diff --stat
git diff檢查：
- 是否只改目標檔案。
- 是否引入無關格式化。
- 是否誤刪 import、型別、測試或註釋。
- 是否寫入本地路徑、賬號、token、客戶名、內部 URL。
- 是否和其他未提交改動衝突。
如果結果不對，優先用 git 判斷，而不是隻依賴 Cascade 的總結。
6. 第五步：決定繼續、回復或提交
第一次閉環有 3 個可能結果：
| 結果 | 下一步 |
|---|---|
| 改動正確、驗證透過 | 可以保留，必要時提交 |
| 改動方向對但不完整 | 讓 Cascade 只做下一小步 |
| 改動越界或不可信 | 回復這次改動，重新限定範圍 |
Windsurf checkpoint 可以用於會話內回退，但商業專案仍以 git 為最終審計面。尤其是多人或多 agent 同時修改時，不能只看 Cascade 自己說“已完成”。
7. 什麼時候升級任務難度
連續 2-3 次小閉環穩定後，再升級：
- 單檔案文案修改。
- 單檔案 bug 修復。
- 同目錄 2-3 檔案修改。
- 補測試。
- 跨模組修復。
- 小功能。
每升一級都先讓 Cascade 輸出 plan。計劃裡必須寫清：
- 要改哪些檔案。
- 為什麼要改。
- 不會改哪些範圍。
- 驗證命令。
- 回復方式。
官方來源
- Welcome to Windsurf —— 官方安裝、首次嘗試和 Cascade 入口。
- Cascade Overview —— 官方 Cascade、tool calling、checkpoint、revert、Problems、linter 和多會話說明。
- Terminal —— 官方終端、Command、auto-execution 和 allow/deny list 說明。
- Windsurf Ignore —— 官方
.codeiumignore和索引排除規則。
本篇自檢
完成練習後，你應該能回答：
- 第一條 prompt 為什麼必須寫"只讀"？
- 為什麼第一次修改只允許單檔案？
- 為什麼要先列驗證命令，而不是直接執行？
- diff 檢查要看哪 5 類風險？
- checkpoint 和 git diff 誰是最終審計面？