Antigravity v1.20.3, released on March 5, 2026, brought a feature that might look small in the changelog but has genuinely changed how I work day to day: support for AGENTS.md.
If you've been using GEMINI.md to guide Antigravity's behavior, you'll find AGENTS.md familiar — but it carries its own distinct purpose. Let me walk you through what it does, how I'm using it, and what's actually changed in my workflow.
What Is AGENTS.md?
AGENTS.md is a Markdown file you place at the root of your project. It gives Antigravity's agents a set of standing instructions — a kind of persistent briefing that the agent reads before starting any task.
The key difference from GEMINI.md is this: where GEMINI.md is mainly about context and preferences (coding style, language choices, project architecture), AGENTS.md is about behavior rules — how the agent should act, what it should check before making changes, and how it should respond when things go wrong.
Think of it as the difference between telling a new teammate "here's what the project does" versus "here's how we work around here."
A Real AGENTS.md Example
Here's a trimmed version of the AGENTS.md I use in my Next.js + Cloudflare Workers project:
# Project Overview
This repo runs on Next.js 16 (App Router) + Cloudflare Workers.
## Agent Instructions
### Before making changes
- Never manually edit files under src/generated/ — these are auto-generated by generate-content.mjs
- After adding or modifying MDX files in content/articles/, always run: node scripts/generate-content.mjs
### Off-limits
- No direct writes to node_modules/
- Never log or commit the contents of .env.local
- Avoid changes that push the Worker bundle over the 62MiB limit
### When errors occur
- Check package.json scripts before attempting any fix
- Identify the root cause of TypeScript errors before suggesting auto-corrections
### Quality checks
- After any code change, run: npm run typecheckThat's it. With this in place, the agent understands the project's constraints from the very first message — no need to re-explain them every session.
What Actually Changed in My Workflow
No more repeated explanations
This is the biggest win. Before AGENTS.md, I'd start every new conversation with a mini-briefing: "This project runs on Cloudflare Workers, so no Node.js fs APIs... and remember to run generate-content.mjs or the article list won't update..." Now that context lives in the file. The agent arrives already knowing it.
Fewer project-specific mistakes
Having the rules written down has noticeably reduced the kind of errors that were quietly frustrating — like the agent editing auto-generated files directly. Since I added that rule to AGENTS.md, it hasn't happened once.
Easier onboarding for collaborators
Because AGENTS.md lives in the repository, anyone joining the project gets the same agent behavior out of the box. You're not just documenting for humans — you're also onboarding the AI.
GEMINI.md vs. AGENTS.md: How I Split Responsibilities
When both files exist, Antigravity reads both. Here's how I personally divide the content:
GEMINI.md (context and style)
- Coding preferences (tabs vs. spaces, naming conventions)
- Framework versions and dependencies
- High-level architecture overview
- Why certain technical decisions were made
AGENTS.md (action rules)
- What commands the agent can and can't run
- Steps required before and after file changes
- How to handle errors
- Quality checks and acceptance criteria
Together, they give the agent both the what and the how — a much more complete picture than either file alone.
Tips for Writing a Good AGENTS.md
After a few rewrites, here's what I've learned:
Use concrete commands, not vague instructions
"Run tests after making changes" is less useful than "After any code change, run npm run typecheck && npm run build." Specificity helps the agent execute without guessing.
Explain the why behind prohibitions
"Don't do X" is fine. "Don't do X because it causes Y" is better. The agent can use that reasoning to make sound judgment calls in edge cases you haven't anticipated.
Keep it focused
It's tempting to document everything, but a bloated AGENTS.md risks burying the important rules. Aim for under 200 lines and prioritize rules that prevent the most costly mistakes.
Revisit it monthly
Projects evolve, and rules that made sense three months ago might be obsolete or even misleading today. A quick monthly review keeps AGENTS.md honest.
Wrapping Up
AGENTS.md is one of those features that doesn't make headlines but genuinely improves the daily experience of working with AI agents. If you've been frustrated by the need to re-explain project context session after session, or by agents that don't know your project's unwritten rules, this is the fix.
v1.20.3's addition of AGENTS.md support signals that the Antigravity team is thinking seriously about long-term, project-integrated workflows — not just single-session coding sprints. Paired with GEMINI.md, it gives you a solid foundation for working with agents that actually know your project.
Try dropping an AGENTS.md into your next project. You might be surprised how much smoother things get.