---
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="/docs/windsurf/understanding/03-cascade-mental-model" description="把单次跑通沉淀成可复用的任务循环" />
  <Card title="上下文 / Rules / AGENTS.md" href="/docs/windsurf/understanding/04-context-rules-agents-md" description="跑通后给项目加规则，让 Cascade 不再失忆" />
  <Card title="终端命令安全" href="/docs/windsurf/understanding/06-terminal-command-safety" description="第一次闭环之后立刻把命令边界写好" />
  <Card title="官方终端能力" href="/docs/windsurf/official/03-terminal-command-control" description="对照官方 allow/deny list 与 auto-execution 设置" />
  <Card title="Understanding 总览" href="/docs/windsurf/understanding" description="回到学习路径地图" />
</Cards>
