Rules 與專案說明檔
Rules 是寫給代理看的持久規範：一份 Markdown 檔，列出你的專案慣例與限制，代理在產生程式碼、使用工具與撰寫測試時都會遵守。不必每次對話都重講一次「用 pnpm、不要改 legacy 目錄」。
兩種寫法
| 寫法 | 位置 | 適合 |
|---|---|---|
| 專案說明檔 | 專案根目錄的 GEMINI.md 或 AGENTS.md |
整個專案通用的目錄結構、程式風格、已棄用 API 提醒 |
| Rules 檔 | 工作區 .agents/rules/，或全域 ~/.gemini/GEMINI.md（CLI 為 ~/.gemini/antigravity-cli/rules/） |
需要分主題、按條件啟用的規範 |
AGENTS.md 是許多代理工具共用的慣例檔名，和其他工具並用時很方便。
啟用方式
單份 Rules 檔有四種啟用模式：
| 模式 | 說明 |
|---|---|
| Manual | 在提示中用 @ 提及該規則才啟用 |
| Always on | 永遠啟用 |
| Model decision | 由模型根據規則的說明，判斷目前是否相關 |
| Glob pattern | 編輯符合指定檔名樣式的檔案時才啟用 |
撰寫限制與技巧
- 每份 Rules 檔上限 12,000 字元，太長就拆成多份。
- Rules 內可用
@檔名引用其他檔案；相對路徑從 Rules 檔所在位置解析。 - 寫可驗證的規則，並附上原因：「所有 API 回傳都用
Result型別，因為前端統一在這一層處理錯誤」比「程式碼要乾淨」有用得多。
範例
一份 Python 專案的 AGENTS.md：
# 專案規範
## 目錄結構
- `src/app/`：應用程式碼
- `tests/`：pytest 測試，檔名以 `test_` 開頭
## 開發指令
- 安裝：`uv sync`
- 測試：`uv run pytest`（修改完成前一定要跑）
- 格式：`uv run ruff format .`
## 風格
- 一律使用型別標註
- 新功能必須附測試
## 注意
- `src/legacy/` 即將移除，請勿在此新增功能
第一次寫不用求完整：先寫開發指令與「最容易被代理做錯的三件事」。之後每次糾正代理，就把那條規則補進去。CLI 的 /learn 指令可以把對話中的修正整理成 Rules 或 Skills，省去手動撰寫。