---
title: "第一次專案閉環"
description: "用只讀理解、單檔案修改、驗證命令和 diff 檢查四步，把 Windsurf 安全放進真實專案。"
verifiedAt: "2026-05-09"
---

第一次用 Windsurf，不要讓 Cascade “重構整個專案”。正確目標是跑通一個低風險閉環：只讀理解專案，限定單檔案修改，執行最小驗證，檢查 diff，然後決定繼續、回復或提交。

> [!TIP]
> **本篇目標**：讓你用真實專案完成第一輪安全驗證，而不是隻在 demo 裡點按鈕。

## 1. 選擇練習專案

練習專案要真實，但不能高風險。

適合：

- 有 git。
- 有清晰目錄結構。
- 有 lint、test 或 build 命令。
- 你知道大概功能範圍。
- 當前分支不是釋出前凍結分支。

不適合：

- 含生產金鑰、客戶資料或未脫敏日誌。
- 沒有版本控制。
- 大量生成物沒有被 `.gitignore` / `.codeiumignore` 排除。
- 正在多人併發大改。
- 一旦誤改就會影響生產後臺、支付、部署或資料庫。

正式開始前先做本地檢查：

```bash
git status --short
git branch --show-current
```

如果已有未提交改動，先確認哪些是你自己的、哪些是別人或其他 agent 的。不要讓 Cascade 在髒工作樹裡無邊界修改。

## 2. 第一步：只讀理解

第一條訊息必須明確“只讀”：

```text
先只读分析这个项目，不要修改文件，不要执行命令。
请输出：
1. 技术栈
2. 主要目录职责
3. 入口文件
4. 测试和构建命令线索
5. 你认为最需要先读的 5 个文件
```

你要檢查它是否準確識別：

- 框架和語言。
- package / config / route / app 入口。
- 測試、lint、build 命令。
- 專案規則檔案，例如 `AGENTS.md`、`.windsurf/rules/`、README。
- 不應讀取的路徑。

如果它一開始讀錯方向，先糾正上下文，不要進入修改。

## 3. 第二步：限定單檔案修改

選擇一個低風險任務：

- 改文案。
- 修 typo。
- 給錯誤提示補上下文。
- 給 README 補一行說明。
- 給小函式補一個明顯缺失的 guard。

提示詞：

```text
只修改这个文件：src/components/example.tsx。
目标：把空状态文案改得更具体。
不要修改其他文件。
不要运行命令。
修改后说明你改了哪几行、为什么改。
```

觀察 3 件事：

1. 是否只改目標檔案。
2. 是否解釋了修改理由。
3. 是否主動擴大範圍、順手重構或格式化無關內容。

如果它越界，立即停下，讓它解釋為什麼改了其他檔案，並用 git diff 自己判斷是否回退。

## 4. 第三步：先列驗證命令

不要讓 Cascade 直接跑它想到的所有命令。先讓它列出最小驗證集：

```text
请列出验证这个改动最小需要运行的命令。
先不要执行。
每条命令说明目的和风险。
```

低風險命令通常包括：

```bash
git diff --stat
git diff
pnpm lint
pnpm test
pnpm run build
```

但命令必須以專案事實為準。沒有 `pnpm` 就不要硬跑 `pnpm`；沒有測試指令碼就先讀 `package.json`、README 或 CI 配置。

## 5. 第四步：檢查 diff

閉環的最後一步不是“測試透過”，而是你看過 diff：

```bash
git diff --stat
git diff
```

檢查：

- 是否只改目標檔案。
- 是否引入無關格式化。
- 是否誤刪 import、型別、測試或註釋。
- 是否寫入本地路徑、賬號、token、客戶名、內部 URL。
- 是否和其他未提交改動衝突。

如果結果不對，優先用 git 判斷，而不是隻依賴 Cascade 的總結。

## 6. 第五步：決定繼續、回復或提交

第一次閉環有 3 個可能結果：

| 結果 | 下一步 |
| --- | --- |
| 改動正確、驗證透過 | 可以保留，必要時提交 |
| 改動方向對但不完整 | 讓 Cascade 只做下一小步 |
| 改動越界或不可信 | 回復這次改動，重新限定範圍 |

Windsurf checkpoint 可以用於會話內回退，但商業專案仍以 git 為最終審計面。尤其是多人或多 agent 同時修改時，不能只看 Cascade 自己說“已完成”。

## 7. 什麼時候升級任務難度

連續 2-3 次小閉環穩定後，再升級：

1. 單檔案文案修改。
2. 單檔案 bug 修復。
3. 同目錄 2-3 檔案修改。
4. 補測試。
5. 跨模組修復。
6. 小功能。

每升一級都先讓 Cascade 輸出 plan。計劃裡必須寫清：

- 要改哪些檔案。
- 為什麼要改。
- 不會改哪些範圍。
- 驗證命令。
- 回復方式。

## 官方來源

- [Welcome to Windsurf](https://docs.windsurf.com/windsurf/getting-started) —— 官方安裝、首次嘗試和 Cascade 入口。
- [Cascade Overview](https://docs.windsurf.com/windsurf/cascade/cascade) —— 官方 Cascade、tool calling、checkpoint、revert、Problems、linter 和多會話說明。
- [Terminal](https://docs.windsurf.com/windsurf/terminal) —— 官方終端、Command、auto-execution 和 allow/deny list 說明。
- [Windsurf Ignore](https://docs.windsurf.com/context-awareness/windsurf-ignore) —— 官方 `.codeiumignore` 和索引排除規則。

## 本篇自檢

完成練習後，你應該能回答：

1. 第一條 prompt 為什麼必須寫"只讀"？
2. 為什麼第一次修改只允許單檔案？
3. 為什麼要先列驗證命令，而不是直接執行？
4. diff 檢查要看哪 5 類風險？
5. checkpoint 和 git diff 誰是最終審計面？

## 接下來去哪

<Cards>
  <Card title="Cascade 心智模型" href="/zh-Hant/docs/windsurf/understanding/03-cascade-mental-model" description="把單次跑通沉澱成可複用的任務迴圈" />
  <Card title="上下文 / Rules / AGENTS.md" href="/zh-Hant/docs/windsurf/understanding/04-context-rules-agents-md" description="跑通後給專案加規則，讓 Cascade 不再失憶" />
  <Card title="終端命令安全" href="/zh-Hant/docs/windsurf/understanding/06-terminal-command-safety" description="第一次閉環之後立刻把命令邊界寫好" />
  <Card title="官方終端能力" href="/zh-Hant/docs/windsurf/official/03-terminal-command-control" description="對照官方 allow/deny list 與 auto-execution 設定" />
  <Card title="Understanding 總覽" href="/zh-Hant/docs/windsurf/understanding" description="回到學習路徑地圖" />
</Cards>
