You wrote a detailed agents.md. Coding conventions, naming rules, error handling patterns, testing frameworks — all carefully documented. And yet, the next time you run the agent, it generates code exactly like it always did, as if your file doesn't exist.
I've been there. agents.md is one of Antigravity's most powerful customization features, but it has more failure modes than the documentation typically describes. Here are six common reasons it might not be working, along with concrete steps to diagnose and fix each one.
Issue 1: The File Isn't Being Read at All
Before anything else, verify the basics: file location and filename.
Antigravity expects agents.md at the project root. A file placed in a subdirectory — or named agent.md without the trailing 's' — will be silently ignored. This mistake is more common than you'd expect.
Run this at your project root:
ls -la | grep -i agentIf agents.md doesn't appear, that's your answer. You can also check Antigravity's Context settings to see which context files are currently loaded. If agents.md isn't listed there, it isn't being read.
One more diagnostic: ask the agent directly, "What system instructions are you currently working with?" If the contents of agents.md don't appear in the response, the file isn't being loaded at all.
For a full reference on agents.md structure and syntax, The Complete Guide to AGENTS.md covers everything you need.
Issue 2: Rules That Work at First, Then Fade Mid-Session
This is a context window problem. Antigravity agents can only reference what fits within their context window. As a session grows longer — with code snippets, explanations, and iterations — the content of agents.md gets pushed outside the window. At that point, the agent behaves as if the file doesn't exist.
The fix isn't to write more detailed rules. It's to write fewer of them.
Think of agents.md as something the agent re-reads at the start of every session. The shorter it is, the more reliably it's applied throughout.
Practical steps:
- Aim for under 300 lines — every line competes with actual code for context space
- Keep only non-negotiable rules — move background explanations and examples elsewhere
- Use
/resetmid-session to reload agents.md when you notice the agent drifting - Start fresh sessions between tasks rather than continuing a single long conversation
Issue 3: Rules That Work Everywhere Except One Specific Task
If your code style rules are respected but testing conventions aren't, the problem is almost always vague language.
# What doesn't work
- Write good tests
- Handle errors appropriately
# What does work
- Use Vitest for all tests (not Jest)
- Structure tests with describe/it blocks
- Use vi.mock() for mocking — jest.mock() is not allowed
- Write test names in JapaneseWords like "good," "appropriate," and "proper" don't give the agent anything concrete to act on. State exactly which tools to use, which to avoid, and what the expected output looks like. The more specific the rule, the more consistently it's applied.
Issue 4: The Agent Reads the Rules But Doesn't Follow Them
If you can confirm the agent is loading agents.md but isn't reflecting the rules in its output, the most likely cause is a rule conflict.
For example: if agents.md says "avoid using TypeScript's any type," but the library documentation the agent is referencing uses any throughout, the agent will often follow the documentation over your rule. Similarly, if you ask for "fast code" in your prompt, the agent may deprioritize agents.md constraints in favor of speed.
Two things that reliably fix this:
- Mention your rules explicitly in your prompt: "Follow the agents.md rules and use Vitest for tests"
- Copy the relevant rule directly into your prompt — inline instructions take precedence over file-level context in most cases
This isn't ideal as a permanent workflow, but it's useful for diagnosing whether a conflict is the root cause.
Issue 5: Sub-Agents in Multi-Agent Setups Don't Respect the Rules
When using Manager-Worker patterns, the Manager agent loads and references agents.md — but Worker agents spawned during task execution often don't inherit those constraints. They start fresh, without the rules you've defined.
The solution is to have the Manager explicitly pass key rules to workers in their initialization instructions:
## Add to agents.md (for Manager agents)
### Rules to Pass to Sub-Agents
Always include the following in any sub-agent instructions:
- Write all code in TypeScript
- Use try-catch for all error handling
- Name files using kebab-case
- Do not leave console.log statements in production codeWith this in place, every Worker the Manager creates will receive the core constraints as part of its initial context. For a broader introduction to multi-agent architecture, Getting Started with Antigravity Multi-Agent Workflows is worth reading alongside this.
Issue 6: Everything Worked Fine Until a Recent Update
Antigravity updates occasionally change how agents.md is parsed. If rules stopped applying after an update, check the official release notes for any agents.md-related changes before doing anything else.
Also verify these common post-update issues:
- No YAML frontmatter at the top of agents.md — it's not needed and can confuse the parser
- File encoding is UTF-8 — particularly relevant if you're on Windows
- Heading depth is reasonable — extremely deep heading hierarchies (
####and below) have caused issues in some versions
If a version issue is suspected, strip agents.md down to 3–5 lines and test whether the agent follows those minimal rules. Add rules back one at a time until the problem reappears. Tedious, but it pinpoints the issue precisely.
The Fastest Fix: Cut Your agents.md in Half
Most agents.md problems come down to three things: wrong location, too much content, or language that's too vague.
If your rules aren't being applied consistently, the fastest path to improvement is usually to cut agents.md to half its current size — keeping only the rules you truly can't live without. The reduction in content often makes a bigger difference than any other change.
For a deeper look at how to structure and maintain custom rules across a project, Mastering Custom Rules and Project Configuration in Antigravity covers the full system in detail.