One of the first walls you hit when handing real work to an Antigravity agent is AGENTS.md being silently ignored. You wrote the rules. You put the file in the project root. And the agent still installs the dependency you specifically forbade. As an indie developer who has been shipping apps since 2014 — wallpaper apps, healing apps, AdMob-monetized utilities — I have wired Antigravity agents into more pipelines than I can count, and I have hit this exact wall enough times to map out a clean diagnostic flow.
Across more than a hundred Antigravity sessions on personal projects, three causes account for roughly all of the "my rules are not being applied" cases I see. Here is how I check for each, in the order I run them.
First, confirm that AGENTS.md was actually read
The cheapest check is also the most decisive. In the chat, send:
Quote three things from my AGENTS.md that I explicitly told you to avoid.
Quote the exact text.
If you get back specific, quoted rules, the file is being read and the problem is elsewhere. If you get vague generalities or unrelated answers, the file is not in the agent's context. Run through the three causes below.
Cause A: The file is not at the workspace root
Antigravity reads AGENTS.md from the root of the currently open workspace — not from your git root. If you opened a sub-package in a monorepo as the workspace, an AGENTS.md sitting at the repository root will not be loaded.
# What does the agent treat as the root?
pwd
# Is AGENTS.md directly under it?
ls -la AGENTS.md
# Any duplicates lurking deeper?
find . -maxdepth 3 -name "AGENTS.md"When I work in a sub-package alone, I drop a focused AGENTS.md into that sub-package. When I open the full monorepo, a single root-level file is enough.
Cause B: The file is too large to fit in context
This is the one most people miss. Once AGENTS.md crosses roughly 3,000 lines, the agent starts truncating it to free up context budget — and the truncation usually drops the rules you most cared about, because critical rules tend to be stated once near the top while elaborations balloon further down.
My rule of thumb is: AGENTS.md stays under 200 lines, and any hard prohibitions live in the first 20 lines. When it grows past that, I split:
project/
├── AGENTS.md # global hard rules (under 200 lines)
├── .agent/
│ ├── style.md # coding style
│ ├── testing.md # test policy
│ └── deploy.md # deploy steps
I leave a single line in AGENTS.md saying "see .agent/ for details." Antigravity will open those files on demand once it knows they exist; what matters is keeping the always-loaded surface small.
Cause C: The conversation has overridden your rules
In a long session, your AGENTS.md content can be pushed out of the agent's effective context by everything you said afterward. Worse, if you ever said "actually, go ahead and use that library this once," that exception now outweighs the original prohibition on every subsequent retry.
Two things help here:
First, when you change your mind about a rule, edit AGENTS.md and start a new session. Don't grant exceptions inside the chat. The file is the single source of truth; let it stay that way.
Second, when a long session starts drifting, just open a fresh one. In my experience anything past about 50 round-trips is a strong candidate for restart. A new session reloads AGENTS.md cleanly at the top of context, and the agent's adherence visibly snaps back.
The shape of an AGENTS.md that actually sticks
For reference, here is the skeleton I converged on after running Antigravity across several parallel app businesses — wallpaper apps, meditation apps, AdMob automation tools — and rewriting this file many times:
# AGENTS.md
## Hard prohibitions
- Do not add new npm packages. Suggest them in the chat; never install.
- Do not modify the `version` field in package.json.
- Do not read or write `.env` files.
## Required checks
- When adding tests, show the full passing log of the existing tests/ suite.
- Any DB schema change must be preceded by a one-paragraph rationale.
## Style
- Stay within TypeScript strict mode.
- Use async/await; do not use Promise.then.
See `.agent/` for detail.The two things that matter most: imperative phrasing ("Do not..." / "Required:") and putting the hard rules first. In my own usage, "Do not X" outperforms "Please avoid X" by something like 20% in observed compliance. Small wording change, surprisingly large effect.
When AGENTS.md actually sticks, Antigravity stops feeling like a coin flip and starts feeling like a reliable collaborator. If you have been fighting the same wall, I hope this flow saves you some time.