My AGENTS.md hit 4,000 tokens last Tuesday and the agent just... stopped reading it. Not metaphorically. It blew past a rule I'd written in 72-point all-caps **NEVER** energy and did the exact thing I'd forbidden, with the serene confidence of a man who has never once seen a wiki. I had become the guy who writes a 30-paragraph Slack message and ends it with "TL;DR: nvm." This is a post about how long an AGENTS.md should be, learned the hard way — by speedrunning every mistake on the leaderboard.
How the file got fat
It started clean. Eleven lines. Beautiful. A haiku of a config.
Then a bug happened.
Every bug after that followed the same ritual. The agent does something cursed — say, git push --force to main because I phrased an instruction ambiguously — and instead of fixing the actual cause, I open AGENTS.md and append a fresh commandment:
## NEVER
- NEVER force-push to main
- NEVER use class components in /web
- NEVER run migrations without `--dry-run`
- NEVER touch the file named `legacy_DO_NOT_TOUCH.ts` (this is rule 12, see also rule 4)
- NEVER assume `prod` means staging it does NOT mean staging
- NEVER (this one is important) skip the changelog
This is the bloat engine, and it runs entirely on my own trauma. Each NEVER is a tiny tombstone for a previous incident. The file stopped being documentation a long time ago. It's a grief journal. By the time I noticed, my ## NEVER section had more entries than my actual feature backlog, and rule 47 was just the word PLEASE with no further context. Even I didn't know what it referred to. It was load-bearing and unexplained, like a foundational comment that says // don't remove this.
The part where the joke turns out to be peer-reviewed
Here's where it stops being funny and starts being cited, which is worse.
There's an actual 2026 paper — Gloaguen et al., Evaluating AGENTS.md (arXiv:2602.11988) — that tested whether these files help coding agents at all. The finding, and I want you to sit in it for a second: context files can reduce task success rates versus giving the agent no repo context whatsoever, while pushing inference cost up over 20%. The money quote needs no translation: "unnecessary requirements from context files make tasks harder, and human-written context files should describe only minimal requirements."
So my grief journal was not neutral. It was actively making the agent dumber AND charging me 20% extra for the privilege. I had built a machine that pays more to perform worse. That's not a config file, that's a subscription to my own bad decisions.
The same paper found the damage scales with what you stuff in: unnecessary requirements are precisely what tank task success, so the longer your file drifts past "minimal," the worse it gets — diminishing returns, then negative returns, while the token bill keeps climbing the whole way. So "how long should my AGENTS.md be" has a clear answer bolted to it: minimal, and not a line past it. Mine was, conservatively, the length of a CVS receipt.
And the kicker: auto-generated context files — the "hey agent, write your own AGENTS.md" move — caused performance drops in 5 of 8 tested settings and added 2.45 to 3.92 extra steps per task. Asking the agent to write its own rules makes it worse at following them. It's the ouroboros of incompetence, and on some level I respect it.
Why the agent literally cannot see your NEVER
The real reason rule 47 got ignored isn't laziness. It's architecture — and this is the part that actually changed how I write these files.
AGENTS.md is not a README. A human reads a README once, maybe, ironically. AGENTS.md gets injected into the context window on every single task. Every line is a recurring tax, re-billed per run. Fine so far — except transformer attention is U-shaped. The Lost in the Middle paper (arXiv:2307.03172) showed accuracy peaks when the key info sits at the start or end of the context and significantly degrades when it's stranded in the middle.
Your 4,000-token scream has a beginning, a middle, and an end. Rule 47 lives in the middle. The middle is precisely where the model's attention goes to die. You wrote your single most important rule into the one region of the context window the model treats like a EULA.
And no, a bigger model does not save you. Chroma's 2025 "context rot" study ran 18 frontier models — GPT-4.1, Claude, Gemini, the whole roster — and every one of them degraded as input grew. The cause is RoPE long-term decay: an architectural property, not a bug that ships a fix next release. You cannot npm update your way out of this. The scream is structurally unhearable.
This is also why it's suddenly everyone's problem. AGENTS.md is a real cross-tool standard — Codex, Cursor, GitHub Copilot (native since August 2025), Jules, Windsurf, Zed — and in late 2025 it was donated to the Agentic AI Foundation under the Linux Foundation umbrella. It's official. Which means everyone now has one, and everyone's is quietly getting longer, one trauma at a time.
Put your AGENTS.md on a diet
I cut mine from 4,000 tokens to about 80 lines and the agent started behaving like it had object permanence again. Here's the checklist — all of it backed by the research above, none of it by vibes:
- Keep the core file minimal — well under ~2k tokens. If it's long, that's a smell, not a flex. Nobody is nodding in admiration at your 600-line config. The research is blunt: include only minimal requirements.
- Delete anything the model already knows. "Write clean code," "use descriptive names," generic language idioms — that's pure token tax on information the model absorbed in the womb.
- Keep negatives few and load-bearing. A
NEVERworks great when it's rare and specific. Each one should name a real, recurring, project-specific failure. If you can't say which incident it prevents,git rmit. - Split, don't append. Push directory-specific rules into nested
AGENTS.mdfiles, so/webrules load only when the agent is actually in/web— not globally, on every task, forever. - Don't let the agent author its own rules. 5 of 8 settings got worse, remember. Curate by hand, like a human with taste, not a markov chain with abandonment issues.
- Put non-negotiables at the top or bottom — never buried mid-file. Respect the U-curve. The middle of the file is where rules go to retire.
- Give every rule an expiry condition. When a bug's root cause gets fixed in actual code — a lint rule, a type, a test — retire the prose rule it spawned. Rules should graduate into automation, not accumulate as scripture.
NEVER force-push to mainis strictly weaker than a branch protection setting that makes it impossible. Be the branch protection rule. - Treat it as a context budget, not a junk drawer. Every line is re-billed every run, in attention and in dollars. Spend like it's your money, because the >20% line item says it is.
The one-line version — the only version that survives the U-curve anyway: your AGENTS.md is a runtime artifact, not a diary. Every time you reach to add a rule, fix the root cause instead. And when you can't, write the shortest possible rule and put it where the model can actually see it.
My file is 80 lines now. Rule 47 is gone. I still have no idea what PLEASE meant, and I have made my peace with that.