Agent Rules & AGENTS.md

---
title: Agent Rules & AGENTS.md
description: Configuring project-level and global guardrails using standard AGENTS.md files.
sidebar:
  order: 2
okf:
  source_of_truth: "sites/agents/src/content/docs/rules.md"
  source_revision: "sha256:462565ff8f78d62cd4af739c1ba716a9781d66783358e25a301eb6dbfd5489c7"
  last_verified: "2026-09-25"
  classified_by: "typesafe-ai/jev"
  verified_by: "pending-human-review"
  disposition: "staged-for-review"
  status: "review-required"
---

Antigravity natively discovers and adheres to instructions and constraints defined in standard Markdown rules files.

---

## The Standard: `AGENTS.md`

While `GEMINI.md` is a vendor-specific format, **`AGENTS.md`** has emerged as the open, multi-tool industry standard supported across modern AI development environments (Cursor, Codex, Antigravity).

Antigravity treats both file names as first-class citizens.

---

## Project-Level Rules (Automatic Discovery)

Place an `AGENTS.md` file at the root of your project:

```text
my-project/
├── .git/
├── AGENTS.md    <-- Automatically discovered and loaded
└── src/
```

As you navigate or edit code, the agent walks up from the current working directory to the repository root and loads any `AGENTS.md` or `GEMINI.md` files it finds. They apply hierarchically to that directory and all subdirectories.

---

## Global Rules (Machine-Wide)

Global rules default to `~/.gemini/GEMINI.md`. To standardize on `AGENTS.md` across your entire system, you have two approaches:

### Option A: Markdown Include Syntax
Inside `~/.gemini/GEMINI.md`, link to your central rules file:
```markdown
@[Global Agent Rules](/home/samob/.config/AGENTS.md)
```
*(Antigravity automatically resolves and expands `@[label](path)` includes up to the rules budget).*

### Option B: Symbolic Link (Cleanest)
Replace the default file with a symlink pointing to your standard configuration:
```bash
ln -sf ~/.config/AGENTS.md ~/.gemini/GEMINI.md
```

Whenever you start a new conversation or launch `agy`, your global rules are loaded immediately.

Antigravity natively discovers and adheres to instructions and constraints defined in standard Markdown rules files.

The Standard: `AGENTS.md`

While GEMINI.md is a vendor-specific format, AGENTS.md has emerged as the open, multi-tool industry standard supported across modern AI development environments (Cursor, Codex, Antigravity).

Antigravity treats both file names as first-class citizens.

Project-Level Rules (Automatic Discovery)

Place an AGENTS.md file at the root of your project:

my-project/
├── .git/
├── AGENTS.md    <-- Automatically discovered and loaded
└── src/

As you navigate or edit code, the agent walks up from the current working directory to the repository root and loads any AGENTS.md or GEMINI.md files it finds. They apply hierarchically to that directory and all subdirectories.

Global Rules (Machine-Wide)

Global rules default to ~/.gemini/GEMINI.md. To standardize on AGENTS.md across your entire system, you have two approaches:

Option A: Markdown Include Syntax

Inside ~/.gemini/GEMINI.md, link to your central rules file:

@[Global Agent Rules](/home/samob/.config/AGENTS.md)

(Antigravity automatically resolves and expands @[label](path) includes up to the rules budget).

Option B: Symbolic Link (Cleanest)

Replace the default file with a symlink pointing to your standard configuration:

ln -sf ~/.config/AGENTS.md ~/.gemini/GEMINI.md

Whenever you start a new conversation or launch agy, your global rules are loaded immediately.