Rules 與 Workflows
基於官方 Rules / Workflows 文件解釋 Antigravity 全域性規則、Workspace 規則、啟用方式、@mentions 與可複用 workflow。
Antigravity 的 Rules 和 Workflows 都是自定義能力，但職責不同。官方文件把 Rules 定義為 agent 需要遵守的手動約束，把 Workflows 定義為可重複執行的一系列步驟或 prompts。
簡單說：Rules 管“長期應該怎麼做”，Workflows 管“這類任務按什麼步驟做”。
閱讀目標：讀完本章，你應該能判斷一條經驗應該寫成 Rule、Workflow，還是保留成普通 prompt。
1. Rules 是長期約束
官方 Rules 文件說明，Rules 是使用者手動定義的 constraints，可以在 local 和 global 層級引導 agent 按你的用例和風格工作。
適合寫進 Rule：
| 內容 | 原因 |
|---|---|
| 程式碼風格 | 每次寫程式碼都應遵守 |
| 測試要求 | 每次改動都要考慮驗證 |
| 檔案結構約定 | 避免 agent 新建錯位置 |
| 禁止觸碰目錄 | 防止越權修改 |
| 提交前檢查 | 保持穩定流程 |
不適合寫進 Rule：
- 單次任務目標。
- 臨時實驗背景。
- 過長外部資料。
- 需要指令碼或模板支撐的複雜流程。
官方說明每個 Rules 檔案限制 12,000 字元。Rule 要寫穩定約束，不要變成專案百科。
2. Global Rules 與 Workspace Rules
官方文件列出兩個落點：
| 型別 | 路徑 | 適合 |
|---|---|---|
| Global Rules | ~/.gemini/GEMINI.md | 個人跨專案習慣 |
| Workspace Rules | <workspace-root>/.agents/rules/ | 當前專案團隊約定 |
官方也說明 Antigravity 現在預設 .agents/rules，同時保留 .agent/rules 向後支援。
真實團隊專案優先放 workspace rules。原因很直接：workspace 檔案可以進入版本控制，團隊成員和 agent 都能看到同一套專案規則；global rules 更適合個人習慣，不適合承載團隊規範。
3. Rule 的啟用方式
官方文件說明，Rule level 可以定義啟用方式。
| 啟用方式 | 含義 | 適合場景 |
|---|---|---|
| Manual | 透過 Agent 輸入框裡的 at mention 手動啟用 | 不常用但需要精確呼叫 |
| Always On | 總是應用 | 專案硬約束 |
| Model Decision | 根據自然語言描述讓模型決定是否應用 | 中等頻率、邊界清楚的規則 |
| Glob | 根據 glob pattern 匹配檔案 | 特定技術堆疊或目錄規則 |
不要把所有規則都設成 Always On。總是注入過多規則會稀釋上下文，也會讓 agent 難以判斷當前任務重點。
4. @ Mentions 怎麼解析
官方文件說明，可以在 Rules 檔案裡用 @filename 引用其他檔案。
解析邏輯要記住：
- 相對路徑：相對 Rules 檔案所在位置解釋。
- 絕對路徑：先按真實絕對路徑解析。
- 如果絕對路徑不存在，會回退到 workspace 下對應路徑。
實操建議：
@../docs/testing.md
@/Users/name/project/spec.md
@README.md不要在團隊 workspace rule 裡引用個人本機私有絕對路徑。別人無法復現，agent 也可能讀不到。
5. Workflows 是可觸發流程
官方 Workflows 文件說明，Workflows 可以定義一系列步驟，引導 Agent 完成重複任務，例如部署服務或響應 PR comments。它們儲存為 markdown 檔案，可以透過 /workflow-name slash command 呼叫。
Rules 和 Workflows 的核心差異：
| 維度 | Rules | Workflows |
|---|---|---|
| 作用層 | prompt 級長期上下文 | trajectory 級步驟序列 |
| 觸發方式 | Always / Manual / Model Decision / Glob | /workflow-name |
| 適合內容 | 約束、習慣、風格、邊界 | 部署、釋出、審查、排障步驟 |
| 檔案限制 | 12,000 字元 | 12,000 字元 |
flowchart TD
Need["要沉澱一條經驗"] --> Always{"每次都必須生效"}
Always -->|是| Rule["Rule"]
Always -->|否| Steps{"是否是一串可重複步驟"}
Steps -->|是| Workflow["Workflow"]
Steps -->|否| Prompt["普通 prompt"]
Workflow --> Slash["用 /workflow-name 呼叫"]
Rule --> Activation["按 Manual / Always / Model Decision / Glob 啟用"]6. Workflow 可以互相呼叫
官方文件說明，Workflow 內可以呼叫其他 Workflows。例如 /workflow-1 裡可以包含“Call /workflow-2”和“Call /workflow-3”。
這適合拆分複雜流程：
/release-check
1. Call /quality-audit
2. Call /build-preview
3. Call /changelog-review
4. 汇总风险，等待用户确认但不要濫用巢狀。每個 workflow 要能單獨解釋“輸入是什麼、輸出是什麼、什麼時候停止”。
深讀：什麼時候讓 Agent 生成 Workflow
官方文件說明，你也可以讓 Agent 根據已有會話生成 Workflows，尤其適合你已經手動帶著 Agent 跑過一串步驟之後。
正確姿勢是先手工跑通，再結晶 workflow。不要在完全沒驗證過的流程上直接讓 agent 生成自動化步驟。否則你沉澱下來的不是最佳流程，而是一次臨時試錯。
本章自檢
完成本章後，用這 3 個問題檢查自己是否真正理解：
- 一條團隊程式碼風格約束應該寫成 Rule 還是 Workflow？
- Workspace Rules 為什麼優先使用
.agents/rules/？ - Workflow 適合沉澱什麼樣的重複任務？
透過標準：你能把“長期約束”和“重複流程”拆開，併為真實專案設計一條 workspace rule 和一條 workflow。
官方來源
- Google Antigravity Rules / Workflows —— 官方說明 Rules、Global / Workspace 落點、啟用方式、@mentions、Workflows 和 workflow 互相呼叫。
- Google Antigravity Settings —— 官方說明可以從 Settings 和 Editor 入口配置 Antigravity。