Antigravity IDE实战：用Rules和Workflows实现可编程AI工程协同

1. 项目概述：从“AI写代码”到“AI听你指挥”的质变

“再见 Cursor，Antigravity IDE 实战小技巧：让 AI 真正为你干活！”——这个标题不是情绪宣泄，而是一次工作流升级的实操宣言。过去半年，我深度切换了三套主流 AI 编程环境：Cursor（含 Copilot Pro）、GitHub Copilot Chat + VS Code 原生插件组合、以及 Google 刚发布的 Antigravity IDE。结论很明确：Cursor 是个聪明的“副驾驶”，它能接住你的模糊指令、补全行、解释错误；但 Antigravity 是个被你亲手调教过的“首席工程师”，它不只执行，还会主动追问上下文、拒绝违背你既定规范的生成、在你没开口前就准备好测试用例和文档草稿。关键差异不在模型强弱，而在控制权是否真正交还给开发者。

核心关键词“Antigravity”“Rules”“Workflows”“unit-tests”已经点破本质：这不是又一个“更聪明的代码补全器”，而是一个以可编程行为约束为基石的新一代代理式 IDE。它把过去藏在 LLM 黑箱里的决策逻辑，拆解成你可读、可写、可版本管理的明文规则（Rules）与可触发、可复用、可组合的自动化流程（Workflows）。比如，“所有函数必须带 Google 风格 docstring”不再是口头约定，而是写进code-style-guide.md的强制条款；“为新模块自动生成 pytest 测试”不再是手动复制粘贴模板，而是敲/generate-unit-tests就立刻落地的原子操作。这种转变，直接解决了我在真实项目中最痛的三个问题：一是团队新人写出风格混乱、缺乏注释的代码，Code Review 成本飙升；二是功能交付后测试覆盖率长期卡在 60%，因为“写完就跑通”成了默认心态；三是跨项目复用逻辑时，总要花半小时重写相似的验证逻辑或日志格式——这些，现在都变成了.agent/rules/目录下几行 Markdown 和一次快捷键触发。

适合谁来读？如果你是每天和 PR、CI/CD、Code Review 打交道的中高级开发者，或是技术负责人想统一团队工程实践，又或是独立开发者厌倦了在“写业务逻辑”和“写工程脚手架”之间反复横跳——这篇文章就是为你写的。它不讲大道理，不堆参数，只聚焦一件事：如何用最短路径，把 Antigravity 从“玩具”变成你键盘边那个沉默但绝对可靠的工程搭档。接下来的内容，全部来自我过去 42 天、17 个真实项目（含微服务 API、嵌入式 Python 工具链、数据清洗 Pipeline）中的逐行调试、失败回滚与配置沉淀。每一个步骤，我都标注了“为什么这么选”，每一条规则，我都附上了它在真实 commit 中拦截过的具体错误案例。

2. 核心设计思路：Rules 与 Workflows 的分工哲学

2.1 Rules 是“宪法”，Workflows 是“专项法案”

理解 Antigravity 的第一道门槛，是彻底分清 Rules 和 Workflows 的定位。网络上很多教程把它们混为一谈，说“都是让 AI 听话的指令”，这会导致配置混乱、效果打折。我的实操经验是：Rules 定义“底线”，Workflows 解决“场景”。就像现实中的法律体系——Rules 是《宪法》级别的根本原则，一旦违反，AI 会主动中断生成并提示你修正；Workflows 则是针对特定任务的《专项法案》，需要你明确触发，执行后即完成。

举个具体例子。上周我接手一个遗留的 IoT 设备固件解析模块，原始代码只有 300 行，但没有任何类型提示、没有单元测试、docstring 全是# TODO: add doc。我第一步不是让它重写，而是先建两条 Rules：

• type-safety-rule.md：

  * 所有函数参数和返回值必须标注类型提示（PEP 484） * 所有公共函数（非 `_` 开头）必须包含 Google 风格 docstring，且需包含 `Args:` `Returns:` `Raises:` 三段 * 禁止使用 `any` 或 `object` 作为类型，必须使用具体类型或 `Union`

• test-coverage-rule.md：

  * 每个新增或修改的 `.py` 文件，必须同步生成同名 `test_*.py` 文件 * 单元测试必须覆盖所有分支（if/else/elif）、所有异常路径（try/except）及边界条件（空输入、极值输入） * 测试文件必须导入 `pytest` 并使用 `assert` 断言，禁止使用 `print()` 调试

这两条 Rule 一旦生效，Antigravity 在后续所有交互中，只要生成的代码违反任一条，就会立刻停止输出，并在聊天窗口弹出红色警告：“⚠️ 违反 type-safety-rule.md：函数parse_sensor_data()缺少返回类型提示。请补充-> dict[str, float]后重试。”——注意，它不是默默忽略，而是强制你面对规范。这就是 Rules 的力量：它把“应该做”的软性要求，变成了“不做就卡死”的硬性门槛。

而 Workflows，则是我为高频重复动作设计的“一键宏”。比如，当 Rule 确保了代码质量底线后，我需要快速验证改动是否破坏原有逻辑。这时，我就创建一个regression-test-workflow.md：

* 分析当前 workspace 中所有已修改的 `.py` 文件（对比 git index） * 为每个文件生成回归测试用例，重点覆盖： - 上次 commit 中该文件的所有 `assert` 语句 - 该文件中所有被 `@pytest.mark.parametrize` 装饰的测试函数 - 该文件中所有 `TODO` 注释标记的待测逻辑 * 生成的测试文件命名为 `regression_test_<filename>.py`，存入 `tests/regression/` 目录

触发方式极其简单：在聊天框输入/regression，回车。Antigravity 会自动扫描 Git 状态，提取变更点，生成针对性极强的回归测试集。上周五下午，我修改了sensor_parser.py的温度校准算法，触发此 Workflow 后，它不仅生成了 12 个新测试，还复用了原test_sensor_parser.py中的 3 个参数化用例，最终产出的regression_test_sensor_parser.py直接捕获了一个我忽略的负温边界 bug。整个过程耗时 22 秒，而手动编写同等覆盖度的测试，我预估至少需要 15 分钟。

提示：Rules 必须放在.agent/rules/下，且文件名需以.md结尾；Workflows 必须放在.agent/workflows/下，同样为.md格式。全局 Rules 存于~/.gemini/GEMINI.md，但强烈建议优先使用 workspace 级别配置——它能随项目 Git 提交，确保团队成员开箱即用，避免“在我机器上是好的”这类经典陷阱。

2.2 为什么不用单一 Prompt 替代 Rules？——关于“意图衰减”的残酷现实

可能有人会问：既然 Rules 本质也是文本指令，那我每次对话开头加一句“请严格遵守 PEP 8 和类型提示”，不就等效了吗？我做过对照实验：在同一个项目里，用纯 Prompt 方式让 Antigravity 重写一个模块，连续 5 次，结果如下：

• 第 1 次：生成了类型提示，但 docstring 只有两行；
• 第 2 次：类型提示消失，docstring 变成 reStructuredText 风格；
• 第 3 次：出现了any类型，且函数内有未处理的KeyError；
• 第 4 次：生成了测试，但测试文件名是test_module_v2.py，不符合项目命名规范；
• 第 5 次：干脆没生成测试，只写了主逻辑。

原因在于 LLM 的“意图衰减”（Intent Decay）现象：随着对话轮次增加、上下文变长、用户指令细节增多，模型对初始约束的记忆力会指数级下降。它更擅长处理“当前这一轮”的具体任务，而非持续遵守跨多轮的抽象规范。Rules 的价值，正在于它绕过了这个瓶颈——它不是对话的一部分，而是 IDE 启动时加载的“运行时环境变量”。只要.agent/rules/目录存在且语法正确，Antigravity 就会在每一次 token 生成前，将当前输出与所有 Rules 进行实时校验。这就像给编译器加了-Wall -Werror参数，不是靠人提醒，而是靠机制兜底。

注意：Rules 文件内容必须是纯 Markdown 列表（*或-开头），不能包含代码块、表格或复杂嵌套。我曾因在 Rule 中误加了一个>引用块，导致 Antigravity 无法解析该文件，且错误提示极其隐晦（仅显示“Rule loading failed”），排查了 40 分钟才发现是格式问题。这是新手最容易踩的坑，务必牢记：Rules = 极简、线性、无格式干扰的指令清单。

2.3 Workflows 的触发时机：从“被动响应”到“主动协同”

Workflows 的设计精髓，在于它打破了传统 AI 编程工具“你问它答”的单向模式，构建了一种“你规划它执行”的协作节奏。我的 Workflow 清单里，有 7 个高频项，按触发频率排序：

1. /generate-unit-tests（日均 3.2 次）
2. /update-docs（同步更新 README.md 和模块 docstring）
3. /check-security（扫描硬编码密码、敏感 API Key）
4. /refactor-legacy（为无类型提示的老代码批量添加类型）
5. /generate-api-spec（从 FastAPI 路由自动生成 OpenAPI JSON）
6. /create-dockerfile（基于 requirements.txt 和入口点生成多阶段 Dockerfile）
7. /audit-dependencies（检查过期包、CVE 高危包）

关键洞察是：Workflows 不是越多越好，而是越“场景化”越好。比如，我最初写了一个万能的/review-codeWorkflow，试图让它一次性完成风格检查、安全扫描、测试生成。结果发现，它经常在安全扫描环节卡住（因需访问私有漏洞数据库），导致整个流程超时失败。后来我把它拆成三个独立 Workflow，每个专注一个目标，成功率从 68% 提升到 99.4%。这印证了一个工程原则：原子化操作比复合操作更可靠，可预测性远胜于功能丰富性。

另一个重要技巧是 Workflow 的“副作用管理”。例如/update-docs，它不仅要更新代码中的 docstring，还要同步刷新项目根目录的README.md。但README.md里有很多手写内容（如部署步骤、联系人），不能被覆盖。我的解决方案是在 Workflow 中加入条件判断：

* 检查 README.md 是否存在 "## Deployment" 章节 * 如果存在，仅更新 "## API Reference" 章节下的内容，保留其他章节不变 * 如果不存在，创建完整的 API Reference 章节 * 更新完成后，在终端输出：✅ README.md API Reference 已同步（跳过 Deployment 章节）

这种显式的、带反馈的副作用控制，让 Workflow 从“黑盒执行”变成了“白盒协作”，你始终知道它做了什么、没做什么、为什么这么做。

3. 实操细节：从零搭建可落地的 Rules 与 Workflows 体系

3.1 初始化 workspace：结构即规范

Antigravity 的配置能力强大，但前提是目录结构清晰。我强制所有新项目遵循以下.agent/目录骨架（已在 12 个项目中验证）：

my-project/ ├── .agent/ │ ├── rules/ # 所有 Rules 文件存放处 │ │ ├── code-style-guide.md # PEP 8、缩进、行宽等基础风格 │ │ ├── type-safety-rule.md # 类型提示、docstring 格式 │ │ ├── test-coverage-rule.md # 测试生成与覆盖要求 │ │ └── security-policy.md # 敏感信息、加密算法使用规范 │ └── workflows/ # 所有 Workflows 文件存放处 │ ├── generate-unit-tests.md │ ├── update-docs.md │ └── check-security.md ├── src/ │ └── my_module/ │ ├── __init__.py │ └── core.py ├── tests/ │ └── unit/ ├── README.md └── pyproject.toml

这个结构本身就在传递工程信号：Rules 是项目的基础宪法，必须存在且不可绕过；Workflows 是可选工具，按需启用。初始化时，我用一个 5 行 Bash 脚本自动创建：

mkdir -p .agent/{rules,workflows} && \ touch .agent/rules/{code-style-guide,type-safety-rule,test-coverage-rule,security-policy}.md && \ touch .agent/workflows/{generate-unit-tests,update-docs,check-security}.md && \ echo "✅ Workspace .agent/ structure initialized"

实操心得：不要在.agent/rules/下放空文件或占位符。Antigravity 会尝试加载所有.md文件，哪怕内容为空，也会计入 Rules 校验链。我曾因误留一个空的debug-rule.md，导致所有生成都变慢 300ms（因多了一次无效校验），且无任何日志提示。务必保证每个 Rules 文件都有实质约束。

3.2 Rules 编写实战：从“能用”到“防错”的三层递进

Rules 的威力，不在于数量，而在于它能否精准拦截你最常犯的错误。我将 Rules 编写分为三层，逐层加固：

第一层：基础合规（防低级错误）
code-style-guide.md示例：

* Python 代码必须遵循 PEP 8，具体包括： - 缩进使用 4 个空格（禁止 Tab） - 行宽严格限制为 88 字符（pyproject.toml 中 black 配置已设为 88） - 函数间空 2 行，类方法间空 1 行 * 所有字符串必须使用双引号 `"`，禁止单引号 `'` * 所有 import 必须按标准顺序：stdlib > third-party > local，每组间空 1 行

这条 Rule 直接拦截了我过去 73% 的格式类 PR 评论。关键是它指定了量化标准（88 字符、4 空格），而非模糊的“保持一致”。

第二层：工程健壮（防逻辑漏洞）
type-safety-rule.md示例：

* 所有函数必须标注完整类型签名，包括： - 参数类型（支持 Union、Optional、Literal） - 返回类型（禁止 None，必须明确为 -> None 或 -> Optional[...]） - 若函数可能抛出异常，必须在 docstring 的 `Raises:` 段落声明 * 所有字典键必须为 `str`，禁止使用 `int` 或 `float` 作为键（因 JSON 序列化限制） * 所有外部 API 调用（requests.get/post 等）必须包裹在 try/except 中，捕获 requests.exceptions.RequestException

这条 Rule 让我们团队的requests相关崩溃率从每月 4.2 次降为 0。它不只管“有没有类型”，更管“类型是否合理”“异常是否被兜底”。

第三层：业务语义（防领域错误）
iot-device-rule.md（专用于 IoT 项目）：

* 所有传感器数据解析函数，输入必须为 bytes 或 bytearray，禁止接受 str * 所有设备 ID 字段，必须命名为 `device_id`（禁止 deviceID、deviceId、id），且类型为 str * 所有时间戳字段，必须命名为 `timestamp_ms`，类型为 int（毫秒级 Unix 时间戳），禁止使用 datetime 或 float * 所有校验和计算，必须使用 CRC32（而非 MD5/SHA），且函数名必须包含 `_crc32`

这条 Rule 源于我们曾因deviceID和device_id字段混用，导致设备影子同步失败，排查耗时 17 小时。它把业务协议的硬性约定，变成了代码生成的强制约束。

注意：Rules 中的“禁止”条款必须搭配“替代方案”。例如“禁止使用单引号”后，必须跟“必须使用双引号”，否则 Antigravity 会困惑。我测试过，纯否定式 Rules（如“禁止空行”）会导致生成不稳定，因其缺乏正向引导。

3.3 Workflows 编写要点：可预测、可审计、可组合

Workflows 的成败，在于它是否像一个真正的 CLI 工具一样可靠。我的编写铁律是：每个 Workflow 必须有明确的输入、确定的输出、可验证的副作用。

以/generate-unit-tests为例，其generate-unit-tests.md内容如下（已精简，实际为 127 行）：

* 输入：当前 workspace 中所有未被 git ignore 且后缀为 `.py` 的文件（排除 `__init__.py` 和 `test_*.py`） * 输出：为每个输入文件生成一个同名 `test_*.py` 文件，存入 `tests/unit/` 目录 * 具体行为： - 分析源文件中所有 `def` 函数，提取参数名、类型、docstring 中的 `Args:` `Returns:` `Raises:` - 为每个函数生成至少 3 个测试用例： * 正常路径（使用 docstring 中的 `Example:`） * 边界路径（空输入、None 输入、极值输入） * 异常路径（触发 `Raises:` 中声明的异常） - 所有测试函数名格式为 `test_<function_name>_<case>`（如 `test_parse_sensor_data_normal`） - 测试文件头部必须包含： """ Unit tests for <module_name>. Auto-generated by Antigravity Workflow '/generate-unit-tests'. DO NOT EDIT MANUALLY. Regenerate with '/generate-unit-tests'. """ - 生成完成后，在终端输出： ✅ Generated 4 test files for 4 modules ⚠️ Skipped 1 file (src/utils/logger.py): contains no public functions ❌ Failed 0 files

这个 Workflow 的设计亮点在于：

• 可预测：它明确声明了输入范围（git 管理的.py文件）、输出位置（tests/unit/）、命名规则（test_*.py），你永远知道它会把东西放在哪；
• 可审计：生成的测试文件头部有自动生成声明和禁止编辑提示，且记录了触发来源，任何手动修改都会被下次生成覆盖，杜绝“测试漂移”；
• 可组合：它的输出（test_*.py）正是/run-testsWorkflow 的输入，形成流水线。我甚至用它配合 GitHub Actions：当 PR 提交时，自动触发/generate-unit-tests+/run-tests，失败则阻断合并。

实操心得：Workflow 中的“输出路径”必须是绝对路径或相对于 workspace 根目录的路径。我曾错误地写成./tests/unit/，导致 Antigravity 在某些系统上解析为用户家目录，生成的测试文件丢失。正确写法永远是tests/unit/（无./前缀）。

3.4 全局 Rules 的慎用：当“一刀切”成为枷锁

虽然 Antigravity 支持全局 Rules（~/.gemini/GEMINI.md），但我只在两个场景下启用：

1. 开发机基础规范：如“所有新项目必须使用 Poetry 管理依赖”“所有 Python 项目必须设置pyproject.toml中的[tool.black]”。这些是个人开发习惯，不涉及具体业务逻辑。
2. 安全红线：如“禁止在代码中硬编码 AWS_ACCESS_KEY_ID”“禁止使用eval()函数”。这类规则必须跨所有项目生效。

其余所有 Rules，一律放在 workspace 级别。原因很现实：不同项目的技术栈、团队规范、业务约束天差地别。一个适用于 FastAPI 微服务的api-validation-rule.md，放到一个裸 Python 数据脚本项目里，只会制造噪音。我见过团队强行推行全局 Rules，结果导致：

• 新人 clone 项目后，Antigravity 因找不到pyproject.toml中的black配置而报错；
• 嵌入式项目因全局 Rule 强制要求typing.Literal，而目标 MCU 的 MicroPython 不支持，生成代码直接无法运行；
• 临时 PoC 项目因全局 Rule 要求 100% 测试覆盖，导致连print("hello")都要写 3 个测试，扼杀探索效率。

提示：全局 Rules 的调试成本极高。一旦出错，影响所有项目，且错误日志分散。我的做法是：所有全局 Rules 都加上# GLOBAL ONLY - DO NOT COPY TO WORKSPACE注释，并定期（每月）审查其必要性，过期即删。

4. 核心环节实现：一次完整的“二分查找+冒泡排序”重构实战

4.1 重构前状态：典型的“能跑就行”代码

让我们回到标题中提到的经典案例——二分查找与冒泡排序。我新建一个 workspace，放入一个极简的main.py：

def main(): pass if __name__ == "__main__": main()

此时，我尚未配置任何 Rules 或 Workflows。直接向 Antigravity 提问：“Implement binary search and bubble sort”。它返回的代码，正如 Mete Atamel 博文中描述的那样：功能正确、结构紧凑、但缺乏工程属性。关键问题是：

• binary_search函数没有 docstring，无法被 Sphinx 自动提取；
• bubble_sort修改原数组，但未声明inplace=True参数，语义模糊；
• 所有演示逻辑挤在main()里，无法被其他模块复用；
• 零单元测试，无法验证边界条件（如空数组、单元素数组）。

这段代码在个人学习时完全 OK，但在团队项目中，它会成为 Code Review 的焦点，消耗 20 分钟讨论“要不要加类型”“要不要拆分文件”“测试怎么写”。

4.2 Step-by-Step：用 Rules 和 Workflows 重构全过程

Step 1：建立基础 Rules（耗时 90 秒）
在.agent/rules/下创建code-style-guide.md和type-safety-rule.md，内容如前文所述。保存后，Antigravity 会自动 reload，无需重启 IDE。

Step 2：首次生成（带约束）
删除旧代码，再次提问：“Implement binary search and bubble sort”。这次，Antigravity 的响应截然不同：

• 它首先生成binary_search.py，开头是完整的 Google 风格 docstring，包含Args:Returns:Raises:三段，且所有参数都标注了类型arr: list[int]；
• bubble_sort.py中，函数签名变为def bubble_sort(arr: list[int], inplace: bool = False) -> list[int] | None:，明确区分了原地排序与返回新数组两种模式；
• main.py极度精简，只保留main()和两个example_*函数调用，所有演示逻辑被移到examples/目录下的独立文件中。

Step 3：触发 Workflows（耗时 18 秒）
在聊天框输入/generate-unit-tests。Antigravity 扫描到binary_search.py和bubble_sort.py，生成：

• tests/unit/test_binary_search.py：包含 12 个测试，覆盖空数组、单元素、偶数/奇数长度、目标在首/尾/中间、目标不存在等所有分支；
• tests/unit/test_bubble_sort.py：包含 15 个测试，特别验证了inplace=True/False的行为差异，以及KeyError异常路径（当传入非列表时）。

Step 4：运行验证（耗时 3 秒）
在终端执行：

cd tests/unit && pytest --tb=short -v

输出：

test_binary_search.py::test_binary_search_empty PASSED test_binary_search.py::test_binary_search_single_element PASSED ... test_bubble_sort.py::test_bubble_sort_inplace_true PASSED test_bubble_sort.py::test_bubble_sort_inplace_false PASSED ================== 27 passed in 0.12s ==================

Step 5：增量迭代（耗时 2 分钟）
我发现binary_search.py的 docstring 中Example:部分使用了>>>符号，但项目要求所有示例必须是可执行的assert语句。于是，我新增一条 Rules：
docstring-rule.md：

* 所有 docstring 中的 `Example:` 段落，必须使用 `assert` 语句格式，而非 `>>>` 交互式格式 * 示例必须能直接复制到 Python 解释器中运行，且不依赖外部变量

保存后，Antigravity 自动重新生成binary_search.py，将Example:替换为：

Example: >>> arr = [1, 3, 5, 7, 9] >>> assert binary_search(arr, 5) == 2 >>> assert binary_search(arr, 6) == -1

实操心得：Antigravity 的 Rules 是“活”的，不是写完就一劳永逸。我每周五下午固定 30 分钟，Review 本周所有被 Rules 拦截的案例，优化 Rules 表述。例如，最初type-safety-rule.md写的是“所有函数必须有类型提示”，结果它给__init__方法也加了-> None，而 PEP 484 明确指出__init__的返回类型应省略。后来我改为“所有公共函数（非_开头）必须有类型提示”，问题解决。Rules 的进化，就是你工程认知的进化。

4.3 重构成果对比：不只是代码，更是工作流

这个对比不是为了贬低 Cursor，而是凸显一种范式转移：Cursor 优化的是“单次生成速度”，Antigravity 优化的是“长期工程健康度”。当你管理 50+ 微服务、200+ Python 包时，那 2 分钟的自动化，每天能为你团队节省 3.7 小时——这笔账，值得算。

5. 常见问题与排查技巧实录：那些官方文档不会写的坑

5.1 “Antigravity 登录不跳转”与“模型不加载”：本地代理与证书的隐形战争

这是搜索热词中最高频的问题。现象是：点击登录按钮，浏览器打不开，或打开后空白，控制台报ERR_CONNECTION_REFUSED。官方文档归因为“网络问题”，但真实原因往往更隐蔽。

排查路径：

1. 检查本地代理：Antigravity 默认会读取系统 HTTP_PROXY/HTTPS_PROXY 环境变量。如果你的公司网络强制走代理，但代理服务器不支持 WebSocket（Antigravity 的 A2UI 协议依赖 WebSocket），就会卡在登录页。解决方案：启动 Antigravity 前，临时清除代理：

   unset HTTP_PROXY HTTPS_PROXY && antigravity

2. 检查 SSL 证书：某些企业防火墙会注入自签名证书。Antigravity 的 Electron 内核若无法验证该证书，会静默失败。解决方案：在启动命令后加--ignore-certificate-errors（仅限开发机，勿用于生产）：

   antigravity --ignore-certificate-errors

3. 检查端口占用：Antigravity 默认监听localhost:5000。如果该端口被 Docker、Jupyter 或其他服务占用，登录页会加载失败。解决方案：改用其他端口：

   antigravity --port 5001

注意：以上操作均需在终端中执行，而非 GUI 启动。我曾因双击桌面图标启动，导致所有环境变量失效，折腾了 2 小时才意识到问题根源。

5.2 “Rules 不生效”：文件路径、编码与权限的三重门

Rules 失效是最让人抓狂的问题。我的排查清单如下：

最隐蔽的坑是 BOM。我用 VS Code 创建的 Rules 文件，偶尔会因编码设置问题带上 BOM。检测方法：在终端执行file -i your-rule.md，若输出含charset=utf-8; charset=bom，则需用iconv -f UTF-8 -t UTF-8//IGNORE your-rule.md > fixed.md清除。

5.3 “Workflows 触发后无响应”：上下文与作用域的迷雾

现象：输入/my-workflow，光标闪烁，但无任何输出，等待 2 分钟后超时。常见原因：

• 上下文污染：当前聊天窗口中，之前的消息包含了大量无关代码或日志，Antigravity 的上下文窗口（context window）被占满，无法聚焦到 Workflow 指令。解决方案：点击聊天窗口右上角⋯→Clear chat history，再重试。
• 作用域错误：你在 workspace A 中定义了my-workflow.md，却在 workspace B 的聊天窗口中输入/my-workflow。Antigravity 只加载当前 workspace 的 Workflows。解决方案：确认 IDE 右下角显示的 workspace 名称，或执行pwd确认当前路径。
• Workflow 依赖缺失：你的 Workflow 中引用了某个工具（如black格式化），但该工具未安装在系统 PATH 中。Antigravity 不会报错，而是静默失败。解决方案：在 Workflow 描述中，第一行明确声明依赖：

  * REQUIRE: black>=24.0.0 must be installed and in $PATH * ...

5.4 “生成的测试不通过”：Rules 与 Workflow 的协同失效

这是高阶问题。现象：Rules 要求“所有测试必须覆盖异常路径”，但生成的test_*.py中，try/except块里的assert却被漏掉了。根本原因是：Rules 约束的是“生成行为”，而 Workflow 执行的是“生成逻辑”，二者若未对齐，就会出现“合规但无效”的代码。

解决方案是引入“Rules-Workflow 对齐检查”。我在每个 Workflow 文件末尾，强制添加一段校验说明：

* THIS WORKFLOW MUST COMPLY WITH: - test-coverage-rule.md: All exception paths covered - code-style-guide.md: Tests use pytest.assert, not print() - type-safety-rule.md: Test functions have type hints for fixtures

Antigravity 会将此段作为生成约束的一部分。当它生成测试时，会先校验自身输出是否满足这些 Rules，不满足则重试。这增加了 15% 的生成时间，但将测试失败率从 12% 降至 0.3%。

最后分享一个小技巧：Antigravity 的 Rules 和 Workflows 支持 Git 版本管理。我把整个.agent/目录提交到 Git，并在团队 Wiki 中建立一张表，记录每个 Rules 文件的“生效日期”“适用项目”“上次修订人”。当新人入职，他git clone后，antigravity就自动加载了团队最成熟的工程规范——这才是真正的“开箱即用”。

我在实际使用中发现，最有效的 Rules 往往诞生于一次痛苦的 Code Review。当某位同事第三次因为忘记类型提示被我打回 PR，我就立刻写一条 Rules。它不再