Antigravity Rules 规则怎么配:GEMINI.md、AGENTS.md 与 24KB 预算裁剪机制

给 Google Antigravity 写的项目规则太长为什么后半截不生效?本文按官方定制系统文档拆解 GEMINI.md、AGENTS.md 与 .agents/rules 的加载顺序、单文件 24KB 截断线及 20000 Token 总预算降级机制。

NNathaniel bigo··原创首发·AI 辅助撰写
10 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 免费账号 账号

结论先说

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

Antigravity 规则文件位置与预算

图:本站根据 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「变笨了、不听话了」。官方文档明确给出了底层裁剪逻辑:

  1. 单文件硬上限(24 KB / 24,000 字节):系统先把规则里的 @标签 内联引用展开,随后检查总字节数。一旦超过 24,000 字节,超出部分会在行边界被直接截断丢弃。所以最重要、绝对不能违反的禁令必须写在文件最前面。
  2. 常驻规则独立总预算(20,000 Token):所有 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。

相关教程

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同模型

  1. 01

    用 Google Takeout 单独备份导出 NotebookLM 笔记本与 Gemini 记录:只勾选指定服务不下载整个云端硬盘的步骤

    想把 NotebookLM 里的几十个研究笔记本、来源副本与音频概览,连同 Gemini 聊天记录一起备份到本地,又怕 Google Takeout 把整个云端硬盘和相册全打包?本文讲清先取消全选、精准勾选两项服务、解压目录查看与跨号迁移的做法。

    Gemini0
  2. 02

    Google Workspace 企业/教育版管理员怎么在后台给成员开启 Gemini 应用、NotebookLM 与设置年龄访问权限

    团队成员或学校师生登录 Google Workspace 账号时提示无权使用 Gemini 或打不开 NotebookLM?本文按 Google 管理控制台官方文档整理服务开关路径、组织部门(OU)与群组放行、18 岁年龄访问权限设置及对话保留合规配置。

    Gemini0
  3. 03

    安卓手机默认助手换成 Gemini 后设闹钟、发短信或控制智能家居失灵怎么办:Workspace 与实用程序扩展开启步骤

    安卓手机把默认语音助手从 Google Assistant 换成 Gemini 后,喊它定闹钟、开手电筒、发短信或开关智能灯全都没反应?本文按官方帮助中心整理实用程序(Utilities)、Google Home 与 Workspace 关联应用开启步骤及锁屏放行设置。

    Gemini0
  4. 04

    Gemini 写长代码或长文档到一半突然停住、格式截断怎么无缝续写:锚点接续指令与 Canvas 分块修改技巧

    让 Gemini 写几百行代码或万字长文时经常写到一半突然停住、Markdown 代码块没闭合,直接回「继续」又重头抄一遍?本文整理字面锚点续写指令、代码块防乱码补齐法与 Canvas 局部圈选修改工作流。

    Gemini0
  5. 05

    NotebookLM 中文音频播客(Audio Overview)高阶玩法:用自定义引导词控制对谈深度、受众水平与重点章节(附模板)

    NotebookLM 生成的中文音频播客总是泛泛而谈、漏掉核心章节或夹杂生僻英文缩写?本文按官方帮助中心整理来源勾选过滤、四种播客格式搭配与三维自定义引导词写法,附 4 套可直接复制的中文控场模板。

    Gemini0
  6. 06

    NotebookLM 添加 YouTube 视频、网页或扫描版 PDF 提示「无法导入来源」怎么办:无字幕、反爬与纯图 PDF 逐项解决

    往 NotebookLM(Gemini Notebook)塞 YouTube 链接、外文网页或扫描教材时总是亮红叹号提示无法导入来源?本文按官方帮助中心逐项排查无字幕视频、反爬动态页与加密纯图 PDF 的替代导入步骤。

    Gemini0

同产品的其他教程

  1. 01

    用 ChatGPT 速读英文产品手册、开源文档与 GitHub Issue 并沉淀团队中文内训手册

    团队引入海外 SaaS 工具或开源框架时,全英文文档晦涩冗长、真正的坑全藏在几十页 GitHub Issue 讨论里。本文分享速读拆解英文手册、归类 Issue 排障库以及重构团队中文内训 SOP 的完整实战流程。

    ChatGPT其他 AI 工具0
  2. 02

    用 ChatGPT 写油猴脚本(Tampermonkey)与浏览器书签小工具解决网页繁琐重复操作实战

    每天在后台系统里重复勾选几十个复选框、手工复制网页表格或清理遮挡阅读的侧边栏,既枯燥又浪费时间。本文分享不会写 JS 也能用 F12 配合 ChatGPT 写出油猴脚本与书签小工具的完整实战流程。

    ChatGPT其他 AI 工具0
  3. 03

    用 ChatGPT 写高质量 SQL 窗口函数(RANK / LAG / SUM OVER)做留存与漏斗分析实战

    做用户留存率、复购间隔与有序转化漏斗时,多层自连接既难读又拖垮数据库,窗口函数则是高效解法。本文整理数据库方言喂数规范、CTE 分层提示词以及用内置沙盒先验证再上线的完整实战流程。

    ChatGPT其他 AI 工具0
  4. 04

    ChatGPT 连接 Canva、Figma、Linear、Jira、Dropbox 等第三方应用搜不到数据或授权失效怎么办

    在 ChatGPT 接入 Canva、Figma、Linear、Jira 或 Dropbox 后,明明显示已连接却搜不到文件工单,或老提示授权失效怎么办?本文拆解账号错绑、OAuth 范围漏选、权限继承与管理员拦截 5 步排障法。

    ChatGPT其他 AI 工具0
  5. 05

    Anthropic Contextual Retrieval(上下文增强检索)是什么、怎么实现:给文档块自动补背景摘要结合缓存降失误率

    长文档切成小块后丢了公司名、年份和主语指代导致 RAG 频频搜错?本文按 Anthropic 官方技术文章详解 Contextual Retrieval 原理、官方公开评测失误率下降 49% 至 67% 的组合架构,以及用 Claude 提示词缓存低成本批量生成切片背景的完整 Python 代码。

    Claude其他 AI 工具0
  6. 06

    RAG 知识库回答不准怎么调优:切片大小(Chunking)、BM25 + 向量混合检索与 Rerank 重排序三步排查法

    搭好的 RAG 企业知识库一问具体型号、报错码或跨行表格就答非所问?本文按 OpenAI 与 Anthropic 官方检索文档,给出先隔离检索与生成故障、再按结构化切片(Chunking)、BM25 加向量混合召回(RRF)与 Rerank 重排序逐层调优的三步法。

    Claude其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~