第一次專案閉環

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
專案迴圈	project loop	跑通第一個完整任務迴圈。
最小閉環	minimal	先跑通最小可用流程。
驗證	verify	確認改動正確。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你用 Windsurf 跑通第一個專案任務迴圈。

你是 Windsurf 首迴圈顧問。

【角色】
Windsurf 首迴圈顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的具體步驟或示例，不停留在「建議」「考慮一下」這類空泛表述。

【輸入】
- 我的專案和技術堆疊：___
- 想先做的任務：___
- 成功標準：___
- 可投入時間：___
- 經驗水平：___

【工作流程】
1. 幫我選第一個小任務
2. 給委派到驗證的步驟
3. 設定把關點
4. 用測試驗證
5. 給覆盤

【輸出規範】
▌一、選任務
▌二、完整步驟
▌三、把關點
▌四、驗證 + 覆盤

【硬約束】
- 第一個任務小而明確
- 關鍵步驟人工確認
- 驗證透過再合併
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

第一次用 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 和索引排除規則。