Antigravity Rules, AGENTS.md, and GEMINI.md: Guiding Coding Agents

GCP Study Hub
November 19, 2026

Rule files in .agents/rules/ or ~/.gemini/config/rules/ and directory-scoped AGENTS.md and GEMINI.md files are the two main ways to supply written instructions to Antigravity. Choosing among them on the Professional Agentic Architect exam comes down to three practical boundaries: where the instructions should apply, when Antigravity should load them into context, and whether you need guidance for the model or hard enforcement on tool calls. Every rule file and markdown instruction file is guidance to the model, not enforcement, which separates written instructions from hooks.

Rule files and activation modes

Rule files live in .agents/rules/ inside a workspace or in ~/.gemini/config/rules/ globally. Each rule file uses frontmatter to set one of four activation modes, controlling when Antigravity loads the rule into context.

  • Always On (trigger: always_on) includes the full rule on every turn, independent of the task. Always-on rules and global rules share a token budget, since each one is in context on every request. The trigger value must be written in snake case, because Antigravity silently discards a rule whose trigger is written as alwaysOn.
  • Model Decision (trigger: model_decision) shows only the rule's description at the start, and the agent decides whether to read the rest of the file. The description is required because it is all the agent sees when making that choice, which also means the agent can decide that a rule does not apply.
  • Glob (trigger: glob) loads the rule automatically whenever the agent works with files matching the patterns listed in its required globs field, such as the file extensions of one language, and leaves it out of context otherwise. Glob rules do not count against the token budget shared by global and always-on rules.
  • Manual (trigger: manual) loads the rule only when a user mentions it, which keeps it out of context until someone asks for it.

Directory scoping with AGENTS.md and GEMINI.md

AGENTS.md and GEMINI.md files take no frontmatter and stay continuously active for their directory. Whenever Antigravity reads or edits a file, it walks up the directory tree from that file's folder to the workspace root and loads every AGENTS.md or GEMINI.md file it finds at each level. Because these files remain active automatically within their scope, no one has to mention them and they do not depend on the agent deciding whether they are relevant.

Where you place an AGENTS.md or GEMINI.md file determines both its reach and whether it is shared through source control:

  • A GEMINI.md file at the repository root applies standing conventions to every task in that repository. Committing it shares those conventions with everyone who opens the repository. A workspace rule file in .agents/rules/ with trigger: always_on satisfies the same repository-wide, committed requirement.
  • An AGENTS.md file inside a specific subdirectory applies only to work within that folder. Committing the file shares the directory standards with the team, and work outside that subdirectory never loads it.
  • A GEMINI.md file in a developer's home folder applies to every project and is not committed with the code.

Because Antigravity walks upward from the target file's folder to the workspace root, root-level conventions apply everywhere in the repository while subdirectory files load only for work inside their own directory.

Guidance versus enforcement with hooks and skills

A rule, regardless of its activation mode, is guidance to the model rather than enforcement. It tells the agent what to do, and the agent decides how to act on it. Skills are also guidance. A skill loads only when the agent judges it relevant to the task, and the agent still chooses whether to use what the skill describes.

Hooks are the enforcement layer. They are configured in .agents/hooks.json and run outside the model at defined points in the agent's loop, so their effect does not depend on what the model chooses. A PreToolUse hook runs before a tool executes, and its matcher can target a tool such as run_command. The hook receives the command, can inspect it, and returns a decision, and a deny decision stops the tool from running.

Timing and purpose separate hooks from each other and from written instructions. A PreToolUse hook acts on a single tool call before it runs, while a PostToolUse hook runs after the tool has finished, so it can respond to a result but cannot prevent the action that produced it. Hooks also act on individual events rather than supplying standing instructions, so GEMINI.md, AGENTS.md, and rule files remain the place for general conventions.

Putting the distinctions together

On the Professional Agentic Architect exam, most configuration decisions here reduce to matching scope, loading behavior, and enforcement strength. Use a committed root GEMINI.md or an always_on rule in .agents/rules/ for repository-wide conventions, place AGENTS.md inside a subdirectory to isolate committed standards to that folder, and use a glob rule when file-pattern conventions should stay out of the shared always-on token budget. Whenever an action must be blocked reliably rather than suggested to the model, enforce it before execution with a PreToolUse hook in .agents/hooks.json.

Our Professional Agentic Architect practice exams test Antigravity rules, AGENTS.md, and GEMINI.md alongside Antigravity hooks and skills, with detailed explanations that drill these distinctions.

Get tips and updates from GCP Study Hub

arrow