结论先说
- Antigravity 同时原生识别
GEMINI.md和AGENTS.md:两者放在任意目录都会按「从当前目录一路向上查找到仓库根」的顺序自动合并并去重;多工具混用团队直接写AGENTS.md最省心。 - 记住两条硬红线:单文件上限
24 KB,常驻总预算20,000 Token:单个规则文件(展开@说明引用后)超过 24,000 字节会按行直接截断;所有常驻规则加起来超出 2 万 Token 的部分,会被降级成「文件路径指针」,不再全文塞进提示词。 - 独立的
GEMINI.md/AGENTS.md不支持顶部 YAML 元数据:它们在所在目录及子目录永远常驻生效;只有放进.agents/rules/*.md的模块化规则,才能配trigger: model_decision实现按需懒加载。 - 个人全局习惯放
~/.gemini/config/,团队共享规范放仓库内:按工作区项目 > 工作区声明配置 > 本机全局配置的优先级覆盖。 - 谷歌账号准备与主力编程订阅入口:使用 Antigravity 全系列客户端需登录符合开放地区与年龄条件的个人谷歌账号,缺号可查看本站 谷歌账号购买说明(含带 2FA 自动发卡的 谷歌邮箱成品号);多工具主力开发订阅总览见 AI 会员充值中心。

图:本站根据 Antigravity Rules 官方文档 整理的示意图
本文根据 Google Antigravity 官方定制系统文档(antigravity.google/docs/rules-workflows)整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是软件界面截图。本站(bigolab.com)不是 Google 官方网站。
适用于谁
- 想给 Antigravity 配置团队代码风格、禁止修改目录或固定测试命令的开发者;
- 把几万字架构手册全塞进
GEMINI.md,结果发现智能体经常漏看后半截要求的人; - 团队里有人用 Antigravity、有人用 Codex 或 Cursor,想共用一份规则文件不维护多套的人。
一、三层规则目录与加载优先级
当你打开一个代码仓库并编辑某个子目录下的文件时,Antigravity 会按固定路径自动搜集规则,并按解析后的真实文件路径做自动去重(同一份文件在一轮对话里绝不会重复注入两次):
| 规则层级 | 存放路径 | 作用域与格式要求 | 典型放置内容 |
|---|---|---|---|
| 目录层级规则 | 任意层级的 GEMINI.md 或 AGENTS.md | 从当前工作目录向上遍历至仓库根(.git 所在层);纯 Markdown,不支持 frontmatter | 仓库级构建命令、前后端子目录各自的框架约束 |
| 工作区模块规则 | 仓库根 .agents/rules/*.md(兼容 .agent/) | 随 Git 提交给全组共享;支持 always_on 常驻或 model_decision 按需触发 | 数据库迁移安全守则、接口错误码字典等专题规范 |
| 本机全局规则 | 用户目录 ~/.gemini/config/ | 对当前电脑上打开的所有项目生效 | 个人偏好的回复语言(如始终用中文解释)、提交信息格式 |
当不同位置出现同名定制项时,官方定义的生效优先级从高到低依次为:工作区项目层级发现 > 工作区 JSON 声明配置 > 本机 ~/.gemini/config/ 全局发现 > 内置默认配置。如果你同时在团队里搭配 Codex 或 Claude Code 协同开发,跨工具共享写法的细节见 AGENTS.md 跨工具编写指南;需要准备谷歌开发账号或对比各家编程会员充值方案,可分别查看 谷歌账号购买说明 与本站 AI 会员充值总览页。
二、为什么规则写太长会「失灵」:24KB 与 2 万 Token 预算
很多开发者习惯把接口文档、历史踩坑记录全往根部 GEMINI.md 里堆,堆到三四万字后觉得 AI「变笨了、不听话了」。官方文档明确给出了底层裁剪逻辑:
- 单文件硬上限(
24 KB/24,000字节):系统先把规则里的@标签内联引用展开,随后检查总字节数。一旦超过 24,000 字节,超出部分会在行边界被直接截断丢弃。所以最重要、绝对不能违反的禁令必须写在文件最前面。 - 常驻规则独立总预算(
20,000Token):所有always_on规则和本机全局规则共用一个独立的defaultRulesBudget(20,000 Token,与 Skills、MCP 工具的预算分开计算)。当常驻规则总和撑爆 2 万 Token 时,排在后面的超额规则不会报错崩溃,但会从「全文内联注入」自动降级为仅保留一行文件路径指针——只有模型自己判断需要去读该文件时才会调用读取工具,约束力自然不如全文常驻那么强。
三、四步搭出既省配额又听话的规则结构

图:本站根据 Antigravity 官方定制指南 整理的示意图
对照上面的预算机制,推荐把仓库规则按这四步拆干净:
1. 仓库根目录只留一份 100 行以内的 AGENTS.md
只写每次对话都必用的核心事实:包管理器是 pnpm 还是 npm、跑单测的准确命令、绝对禁止触碰的目录:
markdown
# 项目全局开发规范
## 构建与校验命令
- 安装依赖统一使用 `pnpm install`,禁止混用 `npm` 或 `yarn`
- 修改 TypeScript 代码后运行 `pnpm typecheck` 确认零类型报错
## 代码与安全红线
- 严禁直接修改 `prisma/migrations/` 下已生成的历史迁移文件
- 严禁硬编码任何密钥或改写 `.env.production`
2. 前后端专属细则下沉到子目录
把 React 组件样式规范放到 apps/web/GEMINI.md,把 Python 接口规范放到 services/api/GEMINI.md。这样你在改后端接口时,前端那几千字样式规则根本不会被向上扫描加载,既省上下文又不串味。
3. 低频长篇规范放进 .agents/rules/ 按需激活
比如「支付回调签名验签规范」平时改 UI 根本用不上,把它单独存为 .agents/rules/payment-security.md 并设为按模型判断触发(model_decision)。平时只注入简短描述,涉及支付代码时再展开全文。
4. 关键操作手动敲 @ 点名加固
在做高风险重构时,直接在聊天输入框敲 @ 呼出引用菜单,选中对应的规则文件附在当前消息里,确保这一回合百分百全文读取。想进一步减少长会话对额度的消耗,可配合阅读 Antigravity 额度限制与省配额技巧。
常见问题
问:同一个目录里既有 GEMINI.md 又有 AGENTS.md,哪个生效?
答:两个都会被自动发现并加载进上下文,不会互相覆盖屏蔽。为避免重复占用 2 万 Token 预算,建议同一个目录里只保留其中一个文件名,把内容合在一处。
问:把操作流程写成 Rule 好,还是写成 Skill(技能)好?
答:只有「绝不能违背的护栏和代码风格」适合写成常驻 Rule;如果是「怎么一步步发版、怎么按模板生成新模块」这类多步骤标准作业程序(SOP),应该写成 .agents/skills/ 下的 Skill,按渐进式披露机制用时再读。
问:改完 GEMINI.md 保存后需要重启 Antigravity IDE 才生效吗?
答:不需要重启软件。保存文件后直接发起新一轮对话(或在旧版命令行使用刷新指令),系统就会按最新文件内容重新计算并注入。
问:国内没有可用的个人谷歌账号,或者重度写代码想搭配其他编程订阅怎么办?
答:可在本站即时选购带独立 2FA 的 谷歌邮箱成品号(首登顺序与 3 天首登质保细则见 谷歌账号购买页),支持支付宝、微信支付与 AlipayHK;若日常还需要高配额终端智能体互补,也可自助兑换 Claude Code 订阅 或 ChatGPT Plus。
0 条评论
还没有评论,来抢沙发~