I Cut My AGENTS.md From 400 Lines to 40

Quick answer (July 2026): An AGENTS.md file is a plain markdown file you commit to your repo that tells AI coding agents how to work in your codebase. It helps, but only when it is short. In a two-week test I trimmed mine from 412 lines to 38, and my agent made fewer wrong-file edits, hit first-try success more often, and burned fewer tokens per task. Bigger is not better. The file competes for the same context window your actual code needs.

I did not expect to write this post.

I expected AGENTS.md to be a set-and-forget win. You write down your conventions once, every agent reads them, everyone ships faster. That is the pitch on agents.md, the open format now used across 60,000-plus open-source repos. Think of it as a README for agents.

For about six weeks my AGENTS.md grew. Every time an agent did something dumb, I added a rule. Do not touch the migrations folder. Always use the repo's fetcher util, never raw fetch. Run pnpm typecheck before finishing. It felt responsible.

Then the agent started getting worse.

The moment it clicked

I gave Codex a two-file bug fix. It edited the wrong file, added a dependency I explicitly banned on line 240 of my AGENTS.md, and left the typecheck broken.

The rule was right there. It just did not weigh enough anymore.

That is the thing nobody told me. Your AGENTS.md does not sit in some special protected slot. It rides in the context window, right below the system prompt, competing with your code, your diff, and the task itself. A 412-line file is 412 lines the model has to hold while also reasoning about your actual bug.

Augment Code put it bluntly in an April 2026 writeup: a good AGENTS.md is a model upgrade, a bad one costs you. I had built the bad one.

There is even research pushback. A 2026 evaluation discussed on Hacker News argued that bloated context files can drag success rates down and push cost up, not the headline you want when you have been diligently adding rules for a month. The thread's most-upvoted take: the only context worth adding is domain knowledge the model genuinely cannot infer from the code itself. Everything else is noise the agent already knows.

What the tools actually read

Worth knowing which agents even parse this file, because they all landed on the same format in 2026.

Claude Code, OpenAI Codex, GitHub Copilot, and Cursor all read AGENTS.md from the working directory up the tree. Codex reads it before doing any work. Most harnesses discover it automatically, no config, no flag.

So the file is high-leverage. Every agent sees it, every task. Which is exactly why bloat hurts so much. A wasteful line is not paid once. It is paid on every single call.

The trim

I deleted first and asked questions later. Here is the rule I used.

If the agent could figure it out by reading the code, it came out.

That killed most of it. The model does not need me to explain that we use TypeScript. It can see the tsconfig. It does not need my folder tour. It has the folders.

What earned its place was the non-obvious stuff. The trap you only learn by getting burned.

# AGENTS.md

## Build & test
- Install: `pnpm i`
- Typecheck (run before finishing any task): `pnpm typecheck`
- Test a single file: `pnpm vitest run path/to/file.test.ts`

## Conventions the code does NOT make obvious
- All network calls go through `lib/fetcher.ts`. Raw `fetch` breaks ret/auth.
- Money is stored in integer cents, never floats. See `lib/money.ts`.
- `db/migrations/` is generated. Never hand-edit; run `pnpm db:gen`.

## Boundaries
- Do not edit anything under `packages/legacy/`. It ships separately.

That is close to my real file. Thirty-eight lines. Every line is something an agent would get wrong without being told, and could not learn from the code alone.

The build and test commands stay because guessing them wastes a whole turn. The three conventions stay because each one caused a real bug. The boundary stays because the agent kept wandering into code it should not touch.

Everything else, the style lectures, the framework explainers, the aspirational "write clean code" line, gone.

The two weeks after

Same project, same kinds of tickets, same agent. I am one developer, so read this as a field note, not a benchmark.

That last row matters more than it looks. When the file is 400 lines, I stop reading it too. It becomes write-only, a graveyard of rules I set once and never revisit. At 38 lines I actually maintain it. When a rule stops being true, I notice, because I can see the whole thing.

This lines up with what GitHub found after studying more than 2,500 repositories in late 2025: the effective files are specific, current, and short. The bloated ones read like documentation nobody updates.

When a longer file is fine

I am not saying 38 lines is the answer for everyone.

A giant monorepo with ten teams and real domain rules the model cannot infer? That file will be longer, and it should be. The test is not line count. The test is whether every line earns its place by preventing a mistake the agent would otherwise make.

Short is a side effect of that test, not the goal.

If you want the deeper version of this argument, my note on reviewing AI-generated code makes the same point from the other side: the bottleneck is rarely generation, it is context and review. And when I run several agents at once with git worktrees, a lean AGENTS.md matters even more, because every worktree pays that context tax in parallel.

What I do now

Once a week I open AGENTS.md and try to delete a line.

If deleting it would cause a bug, it stays. If I cannot remember why it is there, it goes. The file only grows when an agent burns me in a way the code could not have prevented.

It is the most useful config file in the repo. It is also the smallest it has been in months.

FAQ

Covered in the FAQ block below.

P.S. The banned-dependency rule that started all this? Still in the file. Line 22 now, not line 240. The agent listens this time.