---
title: "Rules 與 Workflows"
description: "基於官方 Rules / Workflows 文件解釋 Antigravity 全域性規則、Workspace 規則、啟用方式、@mentions 與可複用 workflow。"
verifiedAt: "2026-05-06"
---

Antigravity 的 Rules 和 Workflows 都是自定義能力，但職責不同。官方文件把 Rules 定義為 agent 需要遵守的手動約束，把 Workflows 定義為可重複執行的一系列步驟或 prompts。

簡單說：Rules 管“長期應該怎麼做”，Workflows 管“這類任務按什麼步驟做”。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能判斷一條經驗應該寫成 Rule、Workflow，還是保留成普通 prompt。

## 1. Rules 是長期約束

官方 Rules 文件說明，Rules 是使用者手動定義的 constraints，可以在 local 和 global 層級引導 agent 按你的用例和風格工作。

適合寫進 Rule：

| 內容 | 原因 |
| --- | --- |
| 程式碼風格 | 每次寫程式碼都應遵守 |
| 測試要求 | 每次改動都要考慮驗證 |
| 檔案結構約定 | 避免 agent 新建錯位置 |
| 禁止觸碰目錄 | 防止越權修改 |
| 提交前檢查 | 保持穩定流程 |

不適合寫進 Rule：

- 單次任務目標。
- 臨時實驗背景。
- 過長外部資料。
- 需要指令碼或模板支撐的複雜流程。

> [!IMPORTANT]
> 官方說明每個 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 下對應路徑。

實操建議：

```text
@../docs/testing.md
@/Users/name/project/spec.md
@README.md
```

> [!WARNING]
> 不要在團隊 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 字元 |

```mermaid
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”。

這適合拆分複雜流程：

```text
/release-check
1. Call /quality-audit
2. Call /build-preview
3. Call /changelog-review
4. 汇总风险，等待用户确认
```

但不要濫用巢狀。每個 workflow 要能單獨解釋“輸入是什麼、輸出是什麼、什麼時候停止”。

<details>
<summary>深讀：什麼時候讓 Agent 生成 Workflow</summary>

官方文件說明，你也可以讓 Agent 根據已有會話生成 Workflows，尤其適合你已經手動帶著 Agent 跑過一串步驟之後。

正確姿勢是先手工跑通，再結晶 workflow。不要在完全沒驗證過的流程上直接讓 agent 生成自動化步驟。否則你沉澱下來的不是最佳流程，而是一次臨時試錯。
</details>

## 本章自檢

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

1. 一條團隊程式碼風格約束應該寫成 Rule 還是 Workflow？
2. Workspace Rules 為什麼優先使用 `.agents/rules/`？
3. Workflow 適合沉澱什麼樣的重複任務？

透過標準：你能把“長期約束”和“重複流程”拆開，併為真實專案設計一條 workspace rule 和一條 workflow。

## 官方來源

- [Google Antigravity Rules / Workflows](https://antigravity.google/docs/rules-workflows) —— 官方說明 Rules、Global / Workspace 落點、啟用方式、@mentions、Workflows 和 workflow 互相呼叫。
- [Google Antigravity Settings](https://antigravity.google/docs/settings) —— 官方說明可以從 Settings 和 Editor 入口配置 Antigravity。

## 接下來去哪

<Cards>
  <Card title="Skills 與漸進載入" description="繼續理解什麼時候應該把能力打包成 Skill，而不是 Rule 或 Workflow。" href="/zh-Hant/docs/antigravity/official/04-rules-workflows-skills/01-skills-progressive-disclosure" />
  <Card title="Agent Modes 與全域性設定" description="把 Rules / Workflows 和 Planning、Fast、許可權策略配合起來。" href="/zh-Hant/docs/antigravity/official/01-agent-manager/01-agent-modes-settings" />
</Cards>
