AGENTS.md Can Only Have 150 Lines in 2026. Here's What to Do With the Rest

Line 212 of your AGENTS.md says: Never change an endpoint without updating the docs.

Someone added it after the last time an agent forgot. The agent changes an endpoint, runs the tests, marks the task done. The docs are untouched. Three hours later a reviewer catches it, and the task goes back for a second round. Nobody is surprised, because line 212 is sitting under 211 other lines that all say always or never.

This is how almost every AGENTS.md (the shared instruction file that Codex, Cursor, and now Claude Code read at the start of a session) ends up. A study of 2,303 context files found they "evolve like configuration code through frequent, small additions". Every mistake becomes a new line. Nothing ever gets removed.

The file has a budget. In 2026 it's about 150 lines, and most teams spend it much faster than they think.

Is there really a 150-line limit on AGENTS.md?

No tool stops loading your file at line 151. The limit is on the reader, not the file.

Here is what the tools themselves say:

• Claude Code docs: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." Claude Code now reads AGENTS.md as project instructions too, so the same advice applies.

• Codex stops adding instruction files once they reach 32 KiB (kilobytes) combined. That is a hard cut, but a very long one.

• The research: the IFScale benchmark gave 20 models up to 500 instructions at once. The best ones stayed near-perfect "through 150 or more instructions before declining".

So 150 is not a file limit. It's roughly where the best models stop following everything, and your AGENTS.md isn't the only thing spending it. The agent's own system prompt, its tool descriptions, your skills, and the task itself all compete for the same attention. We call this the 150-line budget: the number of lines you can write before you're paying for rules the agent won't keep.

Symptoms your AGENTS.md is over budget

You don't get an error. You get these:

• The agent follows a rule one day and skips it the next.

• The same review comment shows up on every third PR (pull request).

• Someone adds "IMPORTANT" to a rule, and a week later adds it to five more.

• A rule is followed in short sessions and broken in long ones.

• Two rules disagree, and which one wins depends on the day.

• New teammates copy the file into a new repo, and the problems come with it.

If three of these sound familiar, the file is doing less than you think.

What happens past the budget: the arithmetic

IFScale's best model (gemini-2.5-pro) scored 98.4% at 100 instructions, 84.8% at 250, and 68.9% at 500.

Turn that into rules dropped per session (illustrative, since IFScale tests keyword instructions in a writing task, not coding rules):

The word that matters is silently. The paper found that as the count rises, the errors are mostly omissions: the rule isn't broken on purpose, it's just not there. Nothing in the output tells you which 38 were dropped.

And it gets worse inside one session. A controlled study of 1,650 Claude Code sessions found about 5.6% lower odds of following a rule for each extra function the agent writes. Long tasks drift.

The part that complicates the story

Here's the concession most "your file is too long" posts skip.

That same 1,650-session study changed the file's size, the rule's position, and the file's structure, and found no detectable effect from any of them. And the ETH Zurich study of AGENTS.md found that the instructions in these files are "well followed by coding agents". Adding the file still didn't raise task success, and it raised cost by over 20%.

So cutting from 400 lines to 150 is not a magic fix. What these studies agree on is simpler: a rule in a markdown file is a request. Sometimes it's kept. You can't tell when it isn't.

The clearest number on this comes from a 2026 paper on coding agents. Even with a memory system that stored the user's corrections, 57.5% of applicable rules were still broken. When the same corrections were turned into checks that had to pass before the agent could finish, violations on new tasks fell from 100% to 2.0%.

Remembering a rule and following it are two different things. That's the real reason the file keeps growing: every new line is an attempt to turn a request into a guarantee, and text can't do that.

What stays in the 150 lines, and what leaves

Before cutting anything, find out which rules are actually being broken. Your agent's past sessions already hold the answer. claude-md-doctor is a free, open-source Claude Code plugin that gives a CLAUDE.md or AGENTS.md a checkup: it splits the file into rules, replays each one against your own session history, and marks it healthy, ignored, or inert (never had a chance to fire). It also suggests which rules should become a hook or a linter. It runs locally with no dependencies, and every finding cites the doc or study behind it.

Then work through the file in this order, cheapest first.

1. Delete what the agent can find out on its own. Folder layouts, "this is a React app", a summary of the architecture. The ETH study found repo overviews don't help, even though they're the most common content. Claude Code's own test is a good one: "Would removing this cause Claude to make mistakes? If not, cut it."

2. Keep the rules that go against the agent's habits. "Use uv, not pip." "Tests live next to the file, not in /tests." These are the lines agents measurably follow, and the ones they'd get wrong without you. A rule the agent would follow anyway is spending budget for nothing.

3. Move procedures out to skills. "How to cut a release" is 30 lines that matter once a week. A skill (a SKILL.md file the agent loads only when the task needs it) costs almost nothing the rest of the time. One warning: move procedures, not constraints. A 2026 benchmark found agents give skill and tool descriptions lower priority than project files. A "never" rule hidden in a skill gets weaker, not stronger.

4. Move must-happen rules out of text entirely. This is the step that actually shrinks the file. If a rule can be checked, it shouldn't be read. There are three kinds of check:

Claude Code's docs say it plainly: CLAUDE.md instructions "are advisory, hooks are deterministic and guarantee the action happens." Line 212 from the opening, never change an endpoint without updating the docs, is a judge rule. It should fire when the agent tries to mark the task done, not wait three hours for a reviewer.

After these four steps, the file gets a lot shorter. What's left is the stuff that can only be said in words: intent, taste, the "why" behind the checks.

What it costs to do this yourself

Steps 1 to 3 are an afternoon. Step 4 is where teams stall, and it's worth being honest about why.

• Every tool has its own hook format. Claude Code hooks live in .claude/settings.json. Your teammates on Codex and Cursor need the same rule written again, their way. Now you maintain three copies.

• You don't know which rules are being broken. Violations are silent omissions. A tool like claude-md-doctor will tell you once, on one machine. Knowing it every week, across a whole team and every agent they use, is a different job.

• Visible checks get gamed. A benchmark of long coding tasks found agents pass every visible test while failing hidden ones, and the gap grows with code size. A check that matches a pattern can be satisfied without keeping the rule. Prefer checks that run real outcomes, like the actual test suite.

• Judges cost tokens. A model checking your model is not free. You'll want to track that cost apart from the work itself.

• Nobody knows where a rule came from. Six months on, no one remembers why line 88 exists or whether it still matters, so nobody dares delete it.

None of this is hard in isolation. It's a few weeks of plumbing that has nothing to do with your product, and it has to be kept alive after the person who built it moves on.

What not to do

• Don't put "IMPORTANT" on everything. Claude Code's docs: "If you emphasize many lines, none of them stands out." Research on capital letters finds they pull the model's attention but don't reliably improve accuracy, and reasoning models barely notice them.

• Don't ship the file /init generated. The ETH study found LLM-written context files did no better than having no file, and developer-written ones did significantly better than LLM-written ones.

• Don't make every check a hard block. An agent that stops every ten minutes gets turned off. Start most rules as advice, and block only what's destructive or expensive.

• Don't answer every repeat mistake with a new line. That's how you got to 400. Ask first whether the mistake can be caught by a check.

What XTrace can help

The XTrace Rulebook is step 4 without the plumbing.

It reads the rules you already have in CLAUDE.md or AGENTS.md and turns them into checks that run in every connected agent. Each rule gets one of the three check types above (linter, hook, or judge) and one of three strengths: Advise (guidance), Gate (a human approves), or Block (the action stops until the rule passes). Judge tokens are tracked separately, so you can see what the checking costs.

Two things are hard to build yourself. You can replay a rule against past sessions before you turn it on, so you see what it would have caught. And every rule is traced back to where it came from, the session or written standard that created it, so line 88 never becomes a mystery. New rules from repeat mistakes show up as proposals for your team to review, not as another line in the file.

Your AGENTS.md goes back to what it's good at: 150 lines of intent. The rules that must hold live somewhere they're checked.

Book a demo →

If you're still trimming, start with the four fixes for CLAUDE.md and skill file bloat and what an agent actually needs loaded. To see which rules your agents break today, coding agent observability is the place to start. For why storing a rule isn't the same as learning it, see what agent procedural memory is.