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。