Antigravity Rules: Set Up Global and Project Instructions

What Are Antigravity Rules?

Antigravity Rules are persistent instructions, coding standards, or architectural constraints that the agent discovers from files and carries into relevant work. A chat prompt usually addresses one conversation. A rule is saved context that can shape later conversations in the scope where Antigravity finds it. That makes Rules useful for decisions you repeatedly explain, such as which test command to run, how to handle generated files, or which database conventions a project follows.

For an Antigravity rules setup, answer three questions: what work the instruction covers, what the agent should do, and what boundary it must respect. Keep it specific enough to act on and small enough to review. Rules do not turn a request into permission for every command or external action. Continue to inspect proposed changes, shell commands, network access, secrets, and destructive operations according to your normal review process.

• Prompt A one-task request for the current conversation.
• Rule A persistent instruction discovered from a supported file and scope.
• Skill A reusable package of task-specific procedures and supporting resources; see the separate Antigravity Skills guide.

Choose Global, Workspace, or Directory Scope

Pick the narrowest scope that still fits the people and projects that need the instruction. A global rule follows your user profile across workspaces, so reserve it for personal preferences that are safe everywhere. A workspace rule stays with a repository and is easier for a team to review in version control. A directory rule is useful when one part of a large project has conventions that should not affect unrelated folders.

Antigravity rules are cumulative: Antigravity gathers the instructions it discovers rather than treating every new file as a replacement for earlier guidance. If two instructions disagree, more specific directory rules take precedence. Avoid writing contradictory global and repository guidance; make the repository rule explain its exception explicitly. The table summarizes the current locations documented for the Antigravity App.

Create a Rule in the Antigravity App

When you add Antigravity rules in the App, open the Customizations panel from the application menu or project settings, choose the Rules tab, and select + Global or + Workspace for the scope you need. The App then gives you a file-based rule that you can review and edit. On the IDE or CLI surfaces, use the documented file locations and check the surface-specific instructions because the controls may be different.

For a repository rule, begin with one recurring decision rather than a broad manifesto. State the files or tasks it applies to, the concrete behavior to follow, and a verification step. Prefer a reviewable instruction such as “run the focused unit tests after changing parser code” over a vague command like “be careful.” Keep project facts in the repository rule so another contributor can inspect and update them with the code.

1. Choose scopeDecide whether the instruction belongs to your profile, the workspace, or a subdirectory.
2. Open RulesIn the App, use Customizations, then Rules; create a Global or Workspace entry.
3. Write one behaviorName its purpose, applicable work, required action, and a useful verification.
4. Review the fileConfirm the saved path and read the final text before relying on it.

Configure Frontmatter and Activation Modes

Standalone AGENTS.md and GEMINI.md files do not use frontmatter. Their Markdown content stays active for the directory scope. Each modular Markdown file under a rules/ directory must start with YAML frontmatter and a valid trigger. The trigger controls when the rule is loaded, so choose it based on how predictable and frequent the covered work is.

Use always_on for a small instruction that should be present on every turn in scope. Use model_decision for a longer guide that should be opened when its description matches the task. Use glob when the rule is tied to file patterns, and include the required globs field. Use manual when the agent should only load the rule after an explicit @ mention. The current documentation lists these four trigger values.

---
trigger: glob
globs: "*.ts, *.tsx"
description: "Apply these conventions when changing TypeScript files."
---

# TypeScript changes

- Keep exported functions typed.
- Run the focused TypeScript test after editing.
- Do not change generated files by hand.

Verify That a Rule Applies

A saved file is not proof that the intended instruction was loaded. Test the rule with a small, low-risk request that clearly matches its scope. For a glob rule, use a file that matches the pattern and a nearby file that does not. For a manual rule, mention it explicitly once and compare the result with a task where you omit the mention. Keep the task narrow enough that you can see whether the rule affected the response.

When reviewing the result, look for the specific behavior you wrote down rather than a general impression that the agent seems more careful. Inspect any changed files and commands. If the expected behavior is absent, verify the path, workspace root, frontmatter spelling, trigger, glob pattern, and whether a more specific rule changes the instruction. Edit one cause at a time, then repeat the same test so you can tell whether the fix mattered.

1. Pick a clear taskUse a small action that should be affected by the rule and avoid risky changes.
2. Check the boundaryFor file-specific rules, compare a matching file with a non-matching one.
3. Inspect evidenceReview the response, commands, files changed, and any test result against the rule text.
4. Repeat after editsChange one scope or trigger detail and rerun the same check.

Troubleshoot and Maintain Rules

If Antigravity rules seem ignored, first make sure the file is in the active workspace and a supported location. Then check the exact filename, the .agents spelling, and any YAML delimiter or indentation errors. A modular rule with no valid trigger may not load as expected. For a glob rule, test a known matching path and review the pattern quoting. A manual rule needs an explicit @ mention; it is not meant to activate automatically.

Rules also have practical context limits. The documentation says each rule file is limited to 24 KB after file includes are expanded, and active global plus always_on rules share a 20,000-token budget. When that aggregate budget is exceeded, the largest rule files can be reduced to path-and-description pointers. Keep always_on content short, move long reference material to a model_decision rule, and use its description to explain when the agent should open it.