I edited apps/web/AGENTS.md to add stricter TypeScript rules, only to watch the agent keep applying the older root-level rule and rewrite my code in the opposite direction. As an indie developer who has been shipping apps since 2014 and crossing 50 million cumulative downloads with my wallpaper and wellbeing-focused titles, I hit this exact pattern in my first week of trying Antigravity on a real monorepo.
The problem is rarely "AGENTS.md is being ignored". More often, multiple AGENTS.md files are loaded at once and the model picks whichever feels more confident at the moment. Antigravity merges AGENTS.md hierarchically, so without a deliberate writing pattern you end up with a context where both rules are present and neither wins reliably. After tracking the behavior on a real project, here is what actually happens and how to fix it.
How Antigravity loads multiple AGENTS.md files
Imagine the agent is editing apps/web/components/Button.tsx. Antigravity walks up the directory tree from that file and collects every AGENTS.md it finds:
apps/web/components/AGENTS.md(deepest, if present)apps/web/AGENTS.mdapps/AGENTS.mdAGENTS.mdat the repo root
The collected files are appended to the context window in the order "repository-wide rules → feature scope → file-adjacent scope". Files added later sit "closer" to the action, and in most cases the deeper rules win. But when the root file uses strong, declarative language and a deeper file uses softer wording, the root rule often dominates anyway. That is the classic source of the "root wins" complaint.
Diagnose which file is actually winning
Before fixing anything, make the conflict visible. The fastest path is to ask the agent directly inside Antigravity's chat:
# Diagnostic prompt — copy and paste
For the file you are about to edit (apps/web/components/Button.tsx),
list every AGENTS.md you are reading rules from. For each file path,
enumerate the rules influencing your behavior. If any rules contradict
each other, name the conflict and explain which one you will follow
and why.If the response cites both "the root rule that says X" and "the apps/web rule that says Y" without acknowledging the contradiction, you have your evidence. I lost hours early on by skipping this step and assuming AGENTS.md was simply broken. Treating the diagnostic prompt as a saved snippet you reach for first removes a lot of guesswork.
You can also open the Manager Surface and check the active context panel — Antigravity lists every AGENTS.md currently loaded for the session, in the order it loaded them.
Avoid conflicts by writing scope into the file
The single most effective change is to put the scope in plain English at the top of every AGENTS.md. Treat the root file as project-wide rules, and treat each subfolder file as an explicit override.
<!-- apps/web/AGENTS.md -->
## Scope of this file
These rules apply only to files under `apps/web/`.
When they conflict with the root AGENTS.md, prefer the rules in this file.
## Type rules (override for apps/web)
- For exported functions, always declare an explicit return type, even when inference works.
- The root rule "keep type annotations minimal" does not apply inside apps/web.The trick is to spell out which root rule is being overridden. Models hesitate when instructions are abstract; once the resolution path is written in plain language, it stops bouncing between the two files. After I introduced this pattern across a monorepo housing several of my published apps, the agent's "first-try-correct" rate roughly doubled in my own daily measurements.
Match the assertiveness of root-level wording
Even with explicit scope, you can still see the root rule win. Almost every time, the cause is tone.
- The root file uses commanding language ("must", "never", "always") while the deeper file uses "prefer" or "should".
- The root file uses universal quantifiers ("for every TypeScript file") that the deeper file doesn't explicitly negate.
Match the strength of the language in your override:
<!-- Before — too weak to override -->
- We try to avoid `any` where possible.
<!-- After — assertive enough to win -->
- Inside this folder, never use `any`. When typing is hard, use `unknown` plus a type guard.It can feel impolite to write commands so bluntly, but AGENTS.md is read by a model, not by a teammate. Choosing language the model parses unambiguously prevents conflicts that would otherwise reach production.
Last resort: collapse into a single AGENTS.md
If you have tried scope and tone and still see flapping behavior, the safest move is to delete the per-folder AGENTS.md files and consolidate everything into one root file with named scope sections.
<!-- Root AGENTS.md -->
# Project-wide rules
(Common conventions go here.)
# Scoped rules
## Additional rules for apps/web/
- Apply this section only when editing files under `apps/web/`.
- (Folder-specific rules.)
## Additional rules for apps/api/
- Apply this section only when editing files under `apps/api/`.
- (Folder-specific rules.)You give up the elegance of file-level locality, but you also delete the precedence variable entirely. The agent has nothing to disambiguate. The repo I run for my own apps now uses this consolidated layout, and the regression rate dropped enough that I have not gone back.
If you suspect AGENTS.md is not being read at all, start with AGENTS.md isn't working? Six common Antigravity symptoms and fixes before tuning precedence. For multi-agent architectures where AGENTS.md is part of a coordination strategy, see AGENTS.md for Multi-Agent Architectures.
A line of configuration tends to compound over months of use. My grandfathers were temple carpenters and used to say that a tilted foundation never straightens itself, no matter how many years pass. Tightening AGENTS.md feels small, but the leverage is real. I hope this saves you the same evenings I lost to invisible conflicts.