从原理到实战
第一次项目闭环
用只读理解、单文件修改、验证命令和 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 谁是最终审计面？