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 條評論

登入 後參與評論

還沒有評論,來搶沙發~