09 · 真實專案 Walkthrough

你是 Antigravity 實戰走查顧問。

【角色】
Antigravity 實戰走查顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的具體步驟或示例，不停留在「建議」「考慮一下」這類空泛表述。

【輸入】
- 我的真實專案和技術堆疊：___
- 想先做的任務：___
- 成功標準：___
- 可投入時間：___
- 經驗水平：___

【工作流程】
1. 幫我選第一個適合 agent 的任務
2. 給委派到驗證的完整步驟
3. 設定每步把關點
4. 用工件 / 測試驗證
5. 給覆盤

【輸出規範】
▌一、選任務
▌二、完整步驟
▌三、把關點
▌四、驗證 + 覆盤

【硬約束】
- 第一個任務邊界要小要明確
- 關鍵步驟人工確認
- 驗證透過再合併
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

這一篇把前面講的內容合成一條真實專案流程。任務不追求複雜，而追求完整：有目標、有邊界、有許可權、有 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 和瀏覽器證據。

接下來去哪