05 · 用 Artifacts 建立驗收工作流

你是 Antigravity 工件審查顧問。

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

【輸入】
- agent 這次產出了什麼工件：___
- 我最關心的影響面：___
- 是否有測試 / 截圖：___
- 專案關鍵路徑：___
- 經驗水平：___

【工作流程】
1. 梳理工件型別及作用
2. 教我按工件系統審查
3. 標出重點核查項
4. 用工件驗證改動
5. 給收尾

【輸出規範】
▌一、工件型別
▌二、按工件審查
▌三、重點核查
▌四、驗證 + 收尾

【硬約束】
- 靠工件審查而非盲信結果
- 影響關鍵路徑的額外核查
- 工件不足時要求補證據
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法

Artifacts 的價值不是“輸出更漂亮”，而是把 agent 工作從黑盒變成可審閱證據。官方 Artifacts 文件把 artifact 定義成 agent 為完成工作或向使用者溝通工作與思考而建立的內容，型別可以包括 rich markdown、diff view、architecture diagram、image、browser recording、code diff 等。官方還明確：artifacts 在 agent 處於 Planning 模式時產生，並同時出現在 Agent Manager 與 Editor 中（前者對 artifacts 的顯示和管理做了最佳化）。這意味著如果你在 Fast 模式下跑任務，agent 不會主動產出可審閱的 artifacts。

這意味著你不需要盯著每個工具呼叫，但你必須能看懂計劃、diff、截圖、錄屏和 walkthrough。商業級驗收的核心不是“agent 說完成了”，而是“證據能不能支撐完成”。

1. Artifact 不是記錄

記錄記錄過程，artifact 承擔驗收。兩者差別很大：

官方 Task List 文件說明，它是一個 markdown list，用於複雜任務的研究、實現、驗證等進度跟蹤。你通常不需要直接編輯它，但需要看它是否真的覆蓋了任務閉環。

2. 任務開始前：Task List

Task List 要回答：

1. 分幾步做？
2. 哪些步驟會改檔案？
3. 哪些步驟會跑命令？
4. 哪些步驟會開啟瀏覽器？
5. 最後怎麼驗收？

如果 task list 只有“implement feature / test feature / finish”，太粗。讓 agent 重寫。

更好的 Task List 應該像這樣：

- 研究目前設定頁結構。
- 定位儲存動作和持久化層。
- 編輯前先輸出 implementation plan。
- 只修改設定頁檔案和對應測試。
- 執行定向測試 + 瀏覽器驗證。
- 輸出 walkthrough，含 diff 摘要和剩餘風險。

這個列表不是為了好看，而是為了防止任務中途變形。只要它缺少 research、implementation、verification 其中任何一環，就要求補齊。

3. 動手前：Implementation Plan

Implementation Plan 要審：

flowchart LR
    Plan["Implementation Plan"] --> Scope["修改範圍"]
    Plan --> Design["技術路線"]
    Plan --> Risk["風險點"]
    Plan --> Verify["驗證方式"]
    Plan --> Rollback["回退方式"]

官方 Implementation Plan 文件強調，plan 是用來架構程式碼庫變更的 artifact，並且通常會在修改前請求使用者 review。你可以點 Proceed 繼續，也可以在 artifact 上評論，讓 agent 縮小範圍、改技術路線或修正理解偏差。

建議把評論寫得像工程約束，而不是像主觀意見：

這個 plan 範圍過大。
請保留第一步分析，但不要改全域 layout。
只允許修改 settings form 和對應測試。
驗證命令限定為 pnpm test settings 和一次 mobile browser 截圖。

4. 生成後：Code Diff

看 diff 不要平均用力，先掃紅線：

如果 diff 變大，讓 agent 解釋每個檔案為什麼必須改。

Diff 審查可以按三層走：

1. 檔案層：是否只改授權路徑。
2. 行為層：是否真的解決目標問題。
3. 維護層：是否引入不必要依賴、格式化或隱式副作用。

不要把 walkthrough 當成 diff 的替代品。Walkthrough 是索引，diff 才是事實。

5. UI 後：Screenshot 和 Recording

UI 任務至少交截圖。涉及互動的任務要交瀏覽器錄屏或可複查 walkthrough。

示例驗收要求：

請在 1440px desktop 和 390px mobile 兩個 viewport 截圖。
請錄製從開啟頁面、點選儲存、看到成功提示的完整流程。

截圖看靜態結果，錄屏看互動路徑。兩者不是替代關係。

官方 Screenshots 文件說明，browser subagent 可以擷取頁面或元素，截圖會儲存為 image artifacts 並支援評論。官方 Browser Recordings 文件說明，瀏覽器動作錄屏也會作為 artifact 儲存，適合回看 agent 實際操作路徑。

所以前端任務最低證據標準應該是：

6. 完成後：Walkthrough

Walkthrough 應該包含：

1. 做了什麼。
2. 改了哪些檔案。
3. 怎麼驗證。
4. 驗證結果。
5. 未覆蓋風險。
6. 如何回退。

差的 walkthrough 只寫“已完成”。好的 walkthrough 能讓另一個人不看聊天記錄也能接手驗收。

官方 Walkthrough 文件說明，它通常在任務實現完成後生成，用簡短 summary 幫使用者回到程式碼庫目前狀態；如果是瀏覽器任務，walkthrough 裡經常包含截圖和錄屏。你要把它當作驗收索引，而不是最終驗收本身。

7. 評論迭代

對 artifact 評論時，儘量繫結具體證據：

8. 一套完整驗收順序

真實專案裡，可以固定成這條流程：

flowchart TD
    Start["收到任務"] --> Task["看 Task List"]
    Task --> Plan["審 Implementation Plan"]
    Plan --> Proceed{"範圍和驗證可接受?"}
    Proceed -->|否| Comment["在 artifact 上評論要求重寫"]
    Comment --> Plan
    Proceed -->|是| Diff["看 Code Diff"]
    Diff --> Evidence["看 Screenshot / Recording"]
    Evidence --> Walk["讀 Walkthrough"]
    Walk --> Verify["跑測試 / 構建 / 手動路徑"]
    Verify --> Accept{"證據一致?"}
    Accept -->|否| Comment
    Accept -->|是| Done["接受結果"]

這個順序的好處是清晰：先批准方向，再審實現，再看使用者路徑，最後跑工程驗證。任何一個環節證據不成立，都回到 artifact 評論，而不是讓 agent 無邊界重做。

本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

1. Task List、Implementation Plan、Walkthrough 分別解決什麼問題？
2. 為什麼截圖和錄屏不能互相替代？
3. 點選 Proceed 前，至少要確認哪幾類風險？

透過標準：你能拿到一次 Antigravity 交付後，按 artifacts 逐項判斷它是否可以被接受。

官方來源

• Google Antigravity Artifacts - 官方定義 artifact，並說明 artifacts 與 feedback 的關係。
• Google Antigravity Task List - 官方說明 task list 以 markdown list 跟蹤複雜任務。
• Google Antigravity Implementation Plan - 官方說明 plan review、Proceed、評論和重新審查流程。
• Google Antigravity Screenshots - 官方說明截圖作為 image artifact 儲存並支援評論。
• Google Antigravity Browser Recordings - 官方說明瀏覽器動作錄屏和 recording artifact。
• Google Antigravity Walkthrough - 官方說明任務完成後的 walkthrough summary 和瀏覽器證據。

接下來去哪