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 和瀏覽器證據。

接下來去哪