When I opened the AGENTS.md I had written three weeks earlier, it had quietly turned into a different document. Working on the same project alongside Antigravity surfaced failure patterns I never saw coming, and just as often I discovered that some rules I had written were wasted ink.
AGENTS.md is not finished the moment you save it. The first version is a hypothesis. Once I started spending fifteen minutes every Friday reviewing my Antigravity sessions and adding a line or two to AGENTS.md, the agent's behaviour visibly settled down. This article shares that loop as a concrete workflow, with templates you can copy.
Looking back, the practice feels closer to journaling than to formal documentation. You are watching how an agent operates inside your specific codebase, then slowly transcribing what you learn. The model itself is the same one anyone else would get; what becomes specific to your project is the surrounding ruleset — tuned to your conventions, your tolerance for risk, and your taste.
Why the First Pass at AGENTS.md Always Falls Short
When I draft an AGENTS.md from scratch, I am writing down the rules that already live in my head. After a few back-and-forths with Antigravity, those rules always have gaps.
There are three reasons. First, my mental model and the agent's interpretation never line up perfectly. "Write tests" sounds unambiguous to me, but Antigravity may not know which framework, which file naming convention, or which level of granularity I want.
Second, the project itself keeps changing. If I introduced zod for input validation last week, AGENTS.md needs a sentence about it, otherwise the agent will keep generating the old hand-written validators.
Third — and this is the important one — agent failure modes cannot be predicted up front. You only learn them by watching the agent fail. Treating AGENTS.md as a release notes-style document, updated as the project evolves, makes the maintenance much easier than treating it as a fixed spec.
The Three Categories I Capture in My Weekly Review
When I sit down for the review, I am looking for "moments of friction" from the past week. There is no need to log everything in real time — just glance through your Antigravity history and pull out the conversations that felt off.
- Things the agent did that I did not want: it touched unrelated files, added a dependency I did not ask for, split commits in a strange way. The Antigravity diff view is your friend here
- Things the agent failed to do that I wanted: it skipped tests, wrote a vague PR description, forgot to install
@types/*. Anything you had to ask for twice belongs here - Moments where the agent looked uncertain: it offered three different implementations, or it rewrote its first attempt almost immediately. That uncertainty is a signal that AGENTS.md is missing decision criteria
I keep these notes in a markdown file or sometimes a sticky in my note app. The location does not matter. What matters is the rhythm: a fixed ten minutes once a week, every week.
When I first started this practice I was tempted to treat the log like an issue tracker, complete with severity levels. That turned out to be overkill. The point is not to triage failures, it is to remember enough about them to translate them into edits next Friday. A short bullet — date, what happened, what I expected — is plenty.
Translating Failure Logs into AGENTS.md Edits
Pasting raw failure logs into AGENTS.md will not help. The translation step — "what instruction would have prevented this next time?" — is where the real work happens.
Here is a real before/after from one of my repositories last week.
# Before
- Write in TypeScript
- Add tests
# After
- New files use TypeScript with strict mode (see `tsconfig.json`)
- Tests live alongside source files as `*.test.ts`, run with Vitest
- One feature per commit; tests and production code go in the same commit
- No `any`. When inference fails, prefer a discriminated unionThe diff is only four lines, but the agent's behaviour shifted noticeably. "Add tests" reads like a gesture; the rewritten version tells the agent where to put the file, which framework to call, and how to size each commit. Combined, those constraints leave very little room for guessing.
I often have Antigravity itself help with this rewriting step. A prompt like "Given this failure log, propose three different one-line additions to AGENTS.md that would prevent it next time" frequently produces phrasings I would not have reached on my own. I always make the final call, but the suggestions are good scaffolding.
For the foundations of writing AGENTS.md, see AGENTS.md guide — How to Write Documentation Antigravity Actually Reads. When the file is already written but feels ignored, Troubleshooting When AGENTS.md Has No Effect is a better starting point.
It is also worth distinguishing rules that constrain how the agent works from rules that describe what the project is. A constraint like "do not introduce new dependencies without asking" belongs in AGENTS.md, but "this app uses Next.js 16 App Router" might belong instead in a README that the AGENTS.md merely references. Mixing the two makes both harder to maintain.
Three Rules to Keep AGENTS.md from Bloating
If you only add lines, your AGENTS.md will become an unread monolith within six months — and the agent will be wasting context window on rules it cannot follow. I keep three rules to fight bloat.
- Only codify failures that happen twice: a single accidental misstep does not deserve a rule. Wait for it to recur
- Merge rules with the same intent: do not split "write tests", "use Vitest", and "place tests next to source" across three bullets. Combine them into one block
- Explicitly delete obsolete constraints: temporary rules from a migration should be removed once the migration is complete. Rules whose status is unclear ("do I still have to follow this?") create more confusion than they prevent
The third rule is the one I forget most often. Stale rules cause Antigravity to suggest the old way of doing things even after the codebase has moved on. Once a month, I scan git log AGENTS.md and revisit any section that has not been touched in six months.
A 30-Minute Weekly Workflow
Having a fixed cadence is what keeps the practice alive. My slot is Friday afternoon, thirty minutes total.
- 5 min: skim the past week's Antigravity sessions and jot down three friction moments
- 5 min: run
git log --since="1 week ago" --onelineand skim AI-authored commits for anything that looks unnatural - 10 min: translate those notes into draft AGENTS.md edits (let Antigravity help with phrasing if useful)
- 5 min: review the diff with
git diff AGENTS.md; check for bloat - 5 min: tag one obsolete rule as a deletion candidate for next week (decisions get a week to settle)
Steps 1 and 2 are observation, step 3 is translation, steps 4 and 5 are pruning. Skipping the pruning is the fastest way to end up with a document nobody reads.
The Three-Layer AGENTS.md Structure I Use
For any project larger than a side experiment, a single root AGENTS.md is not enough. I split it into three layers.
- Root
AGENTS.md: project-wide direction, conventions every directory should follow, commit message format apps/{app-name}/AGENTS.md: framework choices, directory conventions, and auth approach for that specific apppackages/{package-name}/AGENTS.md: package-specific API style, test approach, and external dependencies
Antigravity gives precedence to the AGENTS.md closest to the file it is editing, so deep-layer constraints are the ones that actually bite. Cramming everything into the root file causes rules from one app to leak into another.
One side benefit of this layered approach: when you onboard a new contributor, you do not have to brief them on every project convention at once. They open the directory they will be working in, read the local AGENTS.md, and have just enough context to be productive. The same property helps Antigravity stay focused on the right rules for the file currently in scope.
For more on layered configuration in Antigravity, see Mastering Antigravity Custom Rules and Project Configuration.
Add One Line This Week
You do not need to rewrite AGENTS.md in a single sitting. Somewhere in this week's Antigravity history, there is at least one moment where you had to ask the agent for something twice. Pick that moment and add a single line to AGENTS.md.
Next week, watch whether the same failure recurs. That feedback — failure prevented, or still happening — is what turns AGENTS.md from a static file into something that grows with your project.