How to write an AGENTS.md that agents actually follow

AGENTS.md has quietly become the most important file in a lot of repos — and one of the most misused. It's the file your AI coding agent reads before it does anything (Claude Code calls it CLAUDE.md, others call it AGENTS.md, the idea is the same). Get it right and the agent starts every task oriented and on-side. Get it wrong and it's a wall of rules the agent skims and ignores.

The good news: writing one the agent actually follows comes down to a few clear principles. Here they are.

What AGENTS.md is for

AGENTS.md is the agent's on-ramp to your project. In one short read it should tell the agent: what this is, the rules that must hold, where to find anything else, and the commands it'll need.

The best way to think about it isn't "the rulebook." It's the front door and the map. A new contractor doesn't need your entire wiki on day one — they need orientation and signposts. So does the agent.

The rule: route, don't dump

Here's the mistake nearly everyone makes, including me early on: treat AGENTS.md as the place to put everything, because it's the file you're sure the agent reads. Every convention, every gotcha, every edge case, piled into one file.

It backfires. A long file gets skimmed. The empirical study of context files for agentic coding finds the same thing practitioners learn the hard way — the files that work are focused and point outward, not exhaustive. Past a certain length the agent stops absorbing it, and you've made the most important file the least readable.

Stuart Leo

Everything you add to AGENTS.md makes everything else in it less likely to be read. Length is a cost, not a safety net.

So: route, don't dump. The detail lives in other files. AGENTS.md carries the essentials and points to the rest.

Instructions that actually work

Two kinds of instruction earn their place in the file:

• Prohibitive — the hard boundaries. "Never commit secrets." "Don't add a second payment provider." "Never use --force on the shared branch." Clear, absolute, short. These are the rules worth their lines.
• Conditional — the situational logic. "When adding a route, update the sitemap." "If a test fails, fix it before moving on — don't disable it." These encode how to behave in the cases that come up.

What doesn't earn its place: vague aspiration ("write clean code"), and anything the agent can infer from the codebase itself. Be specific or cut it.

Keeping it under the bloat line

AGENTS.md only decays one way — it grows. Every incident tempts you to add a rule. The discipline that keeps it readable:

1. Cap it at what the agent will actually read — roughly a screen or two.
2. When you reach to add detail, add a pointer instead. New convention → a reference file, linked. New trap → a gotcha file, linked.
3. Review it occasionally and cut. A rule nobody enforces is noise. Delete it.

The test is simple: could the agent read this whole file and retain it? If not, it's too long, and the excess is actively hurting you.

Wiring it to the contextbase

A lean AGENTS.md is only powerful because of what it links to. It's the entry point to your wider contextbase — the briefs, decisions and gotchas that live in docs/. The file points — the contextbase holds. The agent loads the front door every time and follows links to exactly the detail a task needs.

A context file the agent follows is short, specific, and points everywhere else — not a wall of rules it skims.

Start here: read the Router file, line by line, see C² vs native rule files, or read the method.