09 · 真实项目 Walkthrough

这一篇把前面讲的内容合成一条真实项目流程。任务不追求复杂，而追求完整：有目标、有边界、有权限、有 plan、有 diff、有 browser 验证、有 artifact、有回退。

1. 任务定义

给 Antigravity 的任务不要写成“修一下”。应该写成可验收需求：

修复设置页保存按钮点击后没有成功反馈的问题。
边界：
1. 先只读分析并给 implementation plan。
2. 修改范围限制在设置页组件和必要测试。
3. 不改全局主题、路由、部署配置。
4. 修完后启动本地服务，用浏览器验证保存成功和失败两条路径。
5. 交付 diff、desktop/mobile screenshot、walkthrough。

更严格的版本可以加上安全边界：

安全边界：
1. 不访问生产后台、支付页、广告后台或任何需要真实登录的页面。
2. Browser 只允许访问 localhost。
3. Terminal 命令先请求确认。
4. 不读取 workspace 外文件。
5. 不提交 git，不推送，不部署。

这几句会显著降低误触远端系统和扩大修改范围的概率。

2. 选择模式和设置

这类任务虽然小，但涉及 UI、终端和浏览器，建议用 Planning，而不是 Fast。推荐起点：

如果只是改一个按钮文案，可以用 Fast；只要涉及用户路径、错误状态、browser 验证，就用 Planning。

3. 计划审阅

你要让它先输出 plan。审 plan 时看：

如果 plan 里没有浏览器验证，让它补。

计划评论示例：

这个 plan 可以继续，但请调整两点：
1. 不要改全局 toast 系统，只在 settings page 接现有 feedback helper。
2. 验证必须包含保存成功、保存失败、390px mobile 三项。
请更新 implementation plan 后再等待我 Proceed。

官方 Implementation Plan 支持在 artifact 上评论。用评论约束它，比在聊天里模糊说“范围小一点”更稳定。

4. 权限批准

按阶段批准：

flowchart LR
    Read["只读项目"] --> Write["写设置页文件"]
    Write --> Test["运行测试"]
    Test --> Dev["启动本地服务"]
    Dev --> Browser["访问 localhost"]
    Browser --> Artifact["截图 / walkthrough"]

不要一开始批准所有 command。尤其避免：

• rm
• git push
• npm install 或 pnpm add，除非 plan 已说明必要性
• 部署命令
• 访问非任务相关 URL

如果 agent 请求命令，按这个格式判断：

5. 改动验收

代码改完后，不先看它说什么，先看 diff：

1. 文件数量是否合理。
2. 是否改了测试。
3. 是否改全局配置。
4. 是否格式化无关文件。
5. 是否引入新依赖。

如果 diff 过大，要求缩小。

Diff 通过后再看测试。不要反过来。测试通过但 diff 越界，仍然不能接受。

6. 浏览器验证

要求它打开页面验证：

请启动本地服务，打开设置页。
验证：
1. 保存成功时出现成功反馈。
2. 保存失败时出现错误反馈。
3. mobile 宽度下按钮和提示不重叠。
4. console 没有 error。
请交付 screenshot 和 walkthrough。

商业级验收不要只看 happy path。至少要看失败路径和 mobile。

更完整的 browser 验收矩阵：

如果页面有多步交互，例如打开弹窗、修改设置、保存、刷新确认持久化，就要求 browser recording。官方 Browser Recordings 文档说明，录屏会作为 artifact 保存，适合回看实际操作路径。

7. Walkthrough 应该长什么样

合格 walkthrough 包含：

• 问题复现方式。
• 修复点。
• 改动文件。
• 验证命令。
• 浏览器验证路径。
• 截图或录屏。
• 未覆盖风险。

不合格 walkthrough：

已修复保存按钮问题。

更好的 walkthrough 应该接近：

已修复 settings page 保存后无反馈的问题。
改动：
- SettingsForm 复用现有 toast helper。
- 为保存失败路径补错误提示。
- 补保存成功和失败测试。

验证：
- pnpm test settings 通过。
- localhost 设置页保存成功路径通过。
- 390px mobile 下按钮和提示不重叠。
- console 未发现 error。

未覆盖：
- 未连接生产账号。
- 未验证旧浏览器。

8. 接受或回退

如果通过：

1. 保留 diff。
2. 记录验证命令。
3. 自己再跑一次关键路径。
4. 再进入 commit 或发布流程。

如果不通过：

1. 在具体 artifact 上评论。
2. 限定只改失败点。
3. 要求重新验证。
4. 必要时 undo 到上一轮。

回退时不要只删除 conversation。删除 conversation 不等于撤销文件改动。先看 Git diff 或版本控制状态，再决定 undo、revert 或手动修改。

9. 完整流程模板

可以把这一篇压成一条 reusable prompt：

请使用 Planning 模式完成这个前端小任务。

任务：
修复设置页保存按钮点击后没有成功反馈的问题。

边界：
- 先只读分析并输出 implementation plan，不要直接修改。
- 只允许修改设置页组件和必要测试。
- 不改全局主题、路由、部署配置、凭据文件。
- 不提交 git，不推送，不部署。
- Browser 只允许访问 localhost。

验收：
- 保存成功有反馈。
- 保存失败有反馈。
- 390px mobile 下按钮和提示不重叠。
- console 没有 error。
- 输出 diff 摘要、测试结果、desktop/mobile screenshot、walkthrough、未覆盖风险。

如果 Antigravity 生成的 plan 没有覆盖这些验收项，不要点 Proceed。

10. 什么时候不适合让它继续

遇到这些情况，停下来人工判断：

商业级使用 Antigravity 的重点不是“完全自动”，而是让每一步都有明确边界和证据。

本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

1. 为什么真实项目 UI 任务优先用 Planning 而不是 Fast？
2. 为什么要先审 diff，再看 walkthrough？
3. 删除 conversation 为什么不能当成代码回退？

通过标准：你能复制本章 prompt，替换成自己的页面任务，并知道在哪些节点必须暂停审查。

官方来源

• Google Antigravity Agent - 官方说明 Agent 是多步推理系统，并通过 tasks 和 artifacts 沟通。
• Google Antigravity Agent Modes / Settings - 官方说明 Planning、Fast、Artifact Review 和 terminal 自动执行策略。
• Google Antigravity Implementation Plan - 官方说明 plan review、Proceed 和评论机制。
• Google Antigravity Browser - 官方说明 Antigravity 可以控制 Chrome 并使用 separate browser profile。
• Google Antigravity Browser Recordings - 官方说明浏览器动作录屏 artifact。
• Google Antigravity Walkthrough - 官方说明任务完成后的 walkthrough summary 和浏览器证据。

接下来去哪