Google Antigravity Rules: Configuring Workspace Scopes, Guidelines, and Agent Triggers

Google Antigravity rules govern autonomous agent behavior across workspaces through hierarchical Markdown files (GEMINI.md, AGENTS.md, and .agents/rules/*.md). Unlike on-demand skills that activate via slash commands, Antigravity rules enforce persistent coding standards, directory-scoped guardrails, and model triggers while adhering to a strict 24 KB per-file ceiling and 20,000-token rules budget.

What Are Google Antigravity Rules?

Google Antigravity rules are directory-scoped and workspace-level Markdown instructions that enforce engineering standards, tool restrictions, and coding constraints on autonomous AI agents. Unlike skills which package multi-step runbooks loaded on demand, rules provide ambient, continuous behavioral guidance during agent planning and execution loops. They allow teams to declare persistent API contracts, testing requirements, and security boundaries without repeating instructions in every prompt.

In the Google Antigravity Customization System, agent behavior is structured across three distinct customization types: rules, skills, and plugins. Rules serve as the foundational constraints for the agent, establishing non-negotiable boundaries before any code edits, terminal commands, or file mutations occur. When an Antigravity agent plans a task, it checks active rules to determine allowed shell commands, linting conventions, and module boundaries.

As detailed in the official Antigravity specification: “Standalone GEMINI.md / AGENTS.md files do not support frontmatter and are always active for their directory scope.” Google Antigravity discovers workspace rules by traversing upwards from the current working directory to the repository root, loading all GEMINI.md, AGENTS.md, and .agents/rules/*.md files into the agent's context.

For technical teams coordinating guidelines across multiple developer tools, see our comprehensive architectural comparisons on Google Antigravity vs Cursor Rules, Google Antigravity skills, and Claude Skills vs Cursor Rules and AGENTS.md. Primary documentation can be referenced at the Google DeepMind Gemini & Antigravity Documentation.

Where Does Google Antigravity Store and Discover Rules?

Google Antigravity discovers rules across three distinct filesystem locations: workspace root directories (.agents/rules/), directory-level hierarchy files (GEMINI.md and AGENTS.md), and machine-global configurations (~/.gemini/config/). When an agent executes in any folder, it automatically walks upwards from the current working directory to the repository root, discovering and merging all matching rule files. This hierarchical discovery ensures directory-specific constraints apply naturally to subpackages and microservices.

The filesystem structure below illustrates how Google Antigravity discovers and scopes rules in a production monorepo:

my-project/
├── .agents/
│   └── rules/
│       ├── api-safety.md          # Workspace-level rule: applies to entire repo
│       └── testing-policy.md      # Workspace-level rule: test requirements
├── AGENTS.md                      # Root specification: always active
├── GEMINI.md                      # Root guideline: general conventions
├── packages/
│   ├── backend/
│   │   ├── GEMINI.md              # Scoped rule: applies ONLY to backend/ and below
│   │   └── src/
│   └── frontend/
│       ├── GEMINI.md              # Scoped rule: applies ONLY to frontend/ and below
│       └── src/
└── ~/.gemini/config/
    └── rules/                     # Global user rules: applies across all repos on machine

Understanding this directory layout reveals how scoping works in practice. Standalone GEMINI.md and AGENTS.md files do not support YAML frontmatter and apply unconditionally to their parent directory and all nested subdirectories. If a backend developer operates inside packages/backend/src/, the Antigravity agent inherits the root AGENTS.md, the root .agents/rules/api-safety.md, and the nested packages/backend/GEMINI.md, while ignoring packages/frontend/GEMINI.md.

This hierarchical inheritance allows engineering leads to establish repository-wide standards at the root, while individual service owners append specialized framework constraints directly inside their respective package directories.

The 5-Layer Loading Precedence and Resolution Hierarchy

Google Antigravity resolves rule conflicts and instruction overlaps through a deterministic 5-layer loading precedence hierarchy. When multiple rules define conflicting directives—such as differing indentation preferences, conflicting package managers, or contradictory lint thresholds—the higher-priority layer strictly overrides lower-priority instructions.

Antigravity resolves instructions according to this descending priority order:

1. Layer 1: Workspace Project Rules (Highest Priority). Discovered by traversing upwards from the current working directory to the repository root. Includes GEMINI.md, AGENTS.md, and .agents/rules/*.md. Project rules check into version control and always override global user settings.
2. Layer 2: Declared Workspace Configurations. Customizations and rules explicitly referenced in workspace manifest files, such as skills.json or plugins.json located within the project repository.
3. Layer 3: Global Machine Discovery. User-level rules and guidelines stored in ~/.gemini/config/. These apply across every repository opened on the local developer machine.
4. Layer 4: Application Built-in Customizations. Default guidelines, baseline system prompts, and safety constraints bundled directly inside the Antigravity desktop or CLI installation.
5. Layer 5: Global Declared Configurations (Lowest Priority). Explicit configurations listed in machine-wide JSON manifests.

In addition to loading precedence, Antigravity applies strict path deduplication. Even if a rule file is referenced multiple times across symlinks or inherited parent folders, it is resolved to its canonical filesystem path and injected exactly once per conversation turn. This eliminates duplicate token consumption and prevents the model from receiving redundant guidance.

Rule Trigger Modes: Always-On Directives vs Model Decision Triggers

Google Antigravity supports two distinct activation modes for workspace rules: unconditional always-on directives and dynamic model-decision triggers. By choosing the appropriate trigger mode, developers can balance strict policy enforcement against context window economy.

Directory-based GEMINI.md and AGENTS.md files are always active for their entire directory hierarchy. In contrast, modular rule files stored in .agents/rules/*.md can declare activation triggers in their frontmatter header.

Consider a production database safety rule placed in .agents/rules/database-safety.md:

---
name: database-safety
description: Enforces query parameterization, migration dry-runs, and transaction boundaries for database operations.
trigger: model_decision
scope: workspace
author: Platform Security Team
---

# Rule: Production Database Safety Guardrails

When generating SQL, ORM queries, or schema migration scripts:
1. **Parameterized Inputs:** Prohibit raw SQL string concatenation; enforce parameterized queries using prepared statement interfaces.
2. **Migration Rollbacks:** Every schema migration file must include an explicit, tested down-migration script.
3. **Transaction Isolation:** Wrap batch update and delete operations in an explicit database transaction block.
4. **Destructive Queries:** Require human-in-the-loop confirmation before issuing any DROP TABLE, TRUNCATE, or ALTER TABLE DROP COLUMN commands.

When a rule specifies trigger: model_decision, Antigravity injects only the rule's lightweight frontmatter name and description (approximately 35 to 50 tokens) during initial agent planning. The complete rule body is loaded into context only when the autonomous agent determines that the user's objective touches database modifications. Conversely, rules configured with always_on load into every session turn unconditionally.

To generate structured rule headers and validate YAML frontmatter schemas without writing configuration by hand, use our free Custom Instructions Generator and Claude Skill Creator.

Context Budget Economics: The 24 KB File Cap and 20,000-Token Rules Ceiling

To protect model attention and prevent context window exhaustion, Google Antigravity enforces a strict 24,000-byte per-file limit and a dedicated 20,000-token aggregate rules budget. These resource constraints ensure that autonomous agents maintain sharp instruction adherence without diluting their attention across thousands of lines of unindexed text.

According to the official Google Antigravity technical documentation: “Each rule file is capped at 24,000 bytes (after expanding includes) and truncated on line boundaries when over the cap.” Each Google Antigravity workspace rule file is capped at 24,000 bytes after expanding include tags, with excess content truncated strictly on line boundaries.

Beyond individual file limits, the Antigravity runtime partitions memory through strict budget allocations:

• Per-File Ceiling (24,000 Bytes): If an engineer writes a monolithic rule file exceeding 24 KB, Antigravity truncates the file at the nearest newline boundary prior to 24,000 bytes. Directives placed past this ceiling are silently ignored.
• Aggregate Rules Budget (20,000 Tokens): Active always-on and discovered rules share a dedicated 20,000-token allocation (defaultRulesBudget), completely isolated from the separate customization budget reserved for skills, MCP tool definitions, and subagents.
• Automatic Demotion to File Pointers: When an enterprise repository accumulates dozens of rules that collectively exceed 20,000 tokens, Antigravity does not fail. Instead, it automatically demotes lower-priority rules from full inline text to file path pointers. The agent is informed of the rule's location on disk and reads it dynamically using file tools only when relevant.

Google Antigravity allocates a dedicated 20,000-token rules budget (defaultRulesBudget), automatically demoting over-budget rules from inline system instructions to on-demand file path pointers. This design guarantees that critical system memory is never flooded by inactive guidelines.

The Sprawl Moment: When Local Antigravity Rules Vanish on Remote Workstations

A senior infrastructure engineer spends three days fine-tuning a comprehensive set of Antigravity rules for their team's distributed Kubernetes microservices. The rules reside in .agents/rules/deploy-guardrails.md and a root GEMINI.md on their primary Mac laptop, establishing strict checks against unparameterized Helm values, mandating namespace resource limits, and preventing direct edits to production manifests. When a Sev-1 deployment failure triggers at 2:00 AM on a Saturday, the engineer logs in from a spare backup laptop and opens a cloud SSH devbox. When they launch an Antigravity agent to remediate the outage, the agent hallucinates deprecated API versions and pushes an unvalidated config map directly to the cluster. The customized rules and guardrails only existed in uncommitted local stashes on the office MacBook, forcing the engineer to halt the agent, spend forty minutes manually rebuilding the deployment constraints, and verify the cluster by hand while the service outage clock ticks.

How Do Antigravity Rules Compare Across Cursor, Claude Code, and Windsurf?

Google Antigravity rules differ fundamentally from Cursor rules, Claude Code skills, and Windsurf rules in scoping mechanisms, file formats, and trigger models. While Cursor uses file-glob matching (.cursor/rules/*.mdc) and Claude Code relies on on-demand procedural runbooks (SKILL.md), Antigravity combines hierarchical directory traversal with autonomous planner triggers. Understanding these architectural differences allows developers to avoid conflicting instructions when switching across editors and CLI agents.

The comparison table below details the execution characteristics of rules across each primary AI coding assistant:

As shown in the table, attempting to maintain identical guidelines across four different formats leads to severe rule drift. In Cursor, rules use frontmatter glob patterns (see official Cursor Documentation), while Claude Code organizes modular tools inside ~/.claude/skills (see official Claude Code Documentation). When debugging Cursor rule conflicts, consult our guide on fixing Cursor rules not working.

How Can You Synchronize Antigravity Rules Across Multiple Machines and Repositories?

You can synchronize Google Antigravity rules across multiple machines and repositories by establishing a centralized, version-controlled library that bridges editor formats and agent directories. Rather than manually copying GEMINI.md files and .agents/rules/ directories across development boxes, a dedicated skill and rule manager provides automated two-way synchronization. This ensures that every update made on one laptop propagates instantly to all your development environments.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool.

Prompttly provides two-way synchronization between a central cloud library and local .agents/rules/ directories, keeping Antigravity, Cursor, and Claude Code instructions aligned across every machine. With Prompttly, managing rules across complex stacks becomes seamless:

• Two-Way Filesystem Sync: Edits made in your local .agents/rules/ or GEMINI.md sync back to Prompttly, and new rules created in Prompttly write directly into local agent folders.
• Mac Hotkey Palette (<200ms Latency): Hit a single global keyboard shortcut on macOS to open your complete library of rules, prompts, and skills, inserting instructions into any editor, terminal window, or web app in under 200 milliseconds.
• Multi-Tool Compilation: Write a guideline once in Prompttly and compile it deterministically into Google Antigravity rules, Cursor .mdc files, Claude Code skills, and AGENTS.md specifications.
• Version History on Every Surface: Track every change, rollback breaking rule revisions, and review diffs before deploying rules across engineering teams.

For developers managing instructions across growing stacks, explore our operational deep-dives on building an AI prompt library for developers, ChatGPT custom instructions vs Claude skills, and multi-machine AI skill sync with MCP.

Frequently Asked Questions About Google Antigravity Rules

These are the questions software developers and engineering teams most frequently ask when configuring and scoping rules in Google Antigravity.

Related Resources and Next Steps

Explore the complete library management collection on our resources hub. Read our companion analyses on Google Antigravity skills, Google Antigravity vs Cursor Rules, and Claude Skills vs Cursor Rules & AGENTS.md. If you are authoring new instructions or formatting rule packages, generate clean templates using our free Custom Instructions Generator and Claude Skill Creator. When you are ready to eliminate prompt sprawl and keep your rules in sync across every tool and laptop, explore Prompttly pricing and team plans or download the native Prompttly Mac app.