AGENTS.md too long? I cut it from 755 lines to 61. It grew back.

On the morning of 28 August the AGENTS.md in OldMate’s repo was 755 lines long. By the afternoon it was 61. Five weeks later, the instruction files in that repo add up to 341 lines across six files, and I’ve cut them three times.

OldMate is a personal CRM I’m building, and most of it is written by Claude Code agents: 328 of the 406 non-merge commits since 12 August carry a Claude co-author line, and most features are built by agents in their own git worktrees. Nobody told them to grow the file. I had an agent check.

Why does my AGENTS.md keep getting longer?

On the night of 28 August I asked the agent in one of my worktrees: “do you have an instruction telling you to append to the agents.md? Why does it keep growing so much?”

It went looking. There was no CLAUDE.md in the repo or in my home config, no hooks, and an empty memory directory. The only mentions of AGENTS.md in the repo were pointers telling agents to read it. So the growth wasn’t an instruction. It was the shape of the file plus a default.

The shape: the file mirrored the codebase, with headings like ## Screens (7 total) and ## Data Model. When the contact-import commit added a screen, it changed “Screens (6 total)” to “Screens (7 total)” and added a subsection. That was the correct thing to do to that heading. Once a doc lists the code, every change to the code is a required edit to the doc.

The default: after changing something, an agent keeps the docs consistent with the change, and my README called AGENTS.md the place for “full architecture, design bible, and implementation details”. Nothing there says to append, but it reads like a job description. Six commits between 20 and 28 August inserted 91, 91, 69, 50, 45 and 43 lines into the root file.

Then there’s the ratchet. Nothing ever prompts a deletion. Each session starts from a file that looks reasonable that day, so no single agent sees the accumulation, and git merges keep both sides. That’s where the 755 came from: two branches each added to the 558-line file, 32 lines on one and 165 on the other, and the merge was 558 + 32 + 165.

None of this was loaded automatically, either. The Claude Code I ran then (2.1.237) read CLAUDE.md, not AGENTS.md, and the repo had no CLAUDE.md from the end of March until 4 September; the docs say reading AGENTS.md directly needs v2.1.277 or later. Agents presumably found the file through the README, then kept it in sync.

What the git history shows

The first cut took the file from 558 lines to 57. The commit is called “Cut AGENTS.md down to what an agent cannot read off the code”. The 558-line version was 31,483 bytes, mostly a repo tree, a screen inventory, a data-model table and a copy of the design bible. It had also gone stale: it described a speech-to-text pipeline that had since been replaced. The few rules that mattered went into short files beside the code, 52 lines for the mobile app and 18 for the backend.

I started that cut from a stale 558-line copy. Branches merged that morning had already taken the file to 755, so when I pushed I reconciled instead of overwriting: 61 lines in the root file, with 99 and 40 in the mobile and backend files.

The first regrowth was the same evening. At 7:49pm a backup feature grew the backend file from 40 lines to 120. At 10:03pm another commit cut it back to 72, saying the sync work had grown it “by restating the schema a third time”. Here’s every AGENTS.md in the repo, added up.

Watch the blue line first. After the first cut the root file stayed between 46 and 78 lines, so if I’d only looked at it I’d have thought the problem was solved. The mustard line is the real story. The rules moved into per-app files, and those grew. On 20 September the mobile file alone was 218 lines, and the four files held 4,253 words. The single file I cut on 28 August had held 4,264.

Some of that regrowth is fair. Three of the six files belong to apps that didn’t exist at the first cut: the web app, the admin console and the voice gateway. The three files that did exist held 200 lines after the first cut and 181 after the third. They’re at 230 now.

It’s lopsided, too. Since the first cut landed, 44 non-merge commits have touched an AGENTS.md. Thirty-six added more lines than they removed, two broke even, and six took lines out. All six were the cuts: the backend trim on the first evening, the second cut, and four commits that carried the third.

Not everything added is bloat. A line from 24 September says the web build’s connect-src must name the voice gateway’s origins, or production blocks every take while dev works. That’s what the file is for. What’s missing is any step that deletes.

Is a long AGENTS.md actually a problem?

I can’t prove my agents do worse at 755 lines than at 341, and I haven’t tried. Here’s what I can point to.

• Claude Code. The memory docs say to aim for under 200 lines per CLAUDE.md file, because longer files use more context and reduce adherence. Files in subdirectories load on demand, when Claude reads a file there, which is the reason to nest.
• Codex. The AGENTS.md guide says Codex stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB (32,768 bytes) by default. My 558-line file was 31,483 bytes and the 755-line one was 44,930. I haven’t tested what Codex does past the cap, and I’d rather not find out.
• A paper. Evaluating AGENTS.md, a February 2026 paper from researchers at ETH Zurich and LogicStar.ai, found that context files didn’t generally improve task success and raised inference cost by over 20 per cent on average. It calls repository overviews not helpful, while allowing that the files suit non-standard coding practices. A repo tree and a screen inventory made up much of my 558 lines. It’s a benchmark, though, not my repo.

What’s the test for what stays in an AGENTS.md?

On 23 September I told an agent to “drastically trim down claude.md / agents.md” and asked “What actually needs to be in there? Propose a change”. It came back with a test, and I told it to implement the cleanup as proposed. A line stays only if all three are true:

1. Getting it wrong is silent or expensive.
2. Lint, typecheck, tests and the release checks wouldn’t catch it.
3. A comment where you’d be editing the code doesn’t already say it.

What passes looks like this, from the mobile file today:

Migrations are additive only. They run inside getReadyDatabase, so one that throws bricks capture for every user.

Jest runs only __tests__/**/*.test.ts; a .tsx test is silently skipped.

What fails is the repo tree, the screen inventory, the types a test already checks, and the plugin order that’s written in the plugin file. Several cuts needed a new home first, a README or a header comment where the code lives, so I moved the content and then deleted the line.

The agent’s draft came in at 1,170 words across the four files. What landed on 24 September was 1,682, down from 4,253. By 3 October those same four files were at 2,579.

How do I stop an AGENTS.md growing back?

I haven’t solved this. Here’s what I’d do, and which parts I’ve done.

1. Put the rule where the code is edited. Done, mostly. Each app has its own short file, so an agent working on the phone app gets the root file and the mobile one: 162 lines today. Before the first cut it was one file of up to 755 lines, which agents saw only when they went and opened it. Better still is a comment at the line it guards, or a test. The .tsx rule above could be a failing check, or the Jest match could be widened so the trap doesn’t exist. Neither is done.

2. Write the file’s contract inside it. Not done. The agent suggested this on 28 August, and it still isn’t in the file:

This file carries only what an agent cannot read off the code. If a section becomes
derivable from the source, delete it rather than extend it. A new feature is not a
reason to add a section.

That flips the default from “keep the docs in sync” to “keep the docs small”.

3. Delete on a schedule. Not done. My cuts were 7 and 20 days apart, and it’s been 13 days since the last. In the nine days after it the files grew by 100 lines, 11 of them a new file for the admin console. I wrote about a weekly subtract day for code in 2024. The instruction files need one too.

4. Watch the size in git. Done for this post, not automated. This prints the root file’s lines and words at every commit that changed it. Leave out --follow: it hides merge commits, and my 755 only shows up as one.

for c in $(git log --reverse --format=%h -- AGENTS.md); do
  echo "$(git show -s --format=%cs "$c") $c $(git show "${c}:AGENTS.md" 2>/dev/null | wc -lw)"
done

And this adds up every AGENTS.md at any commit:

total() {
  git ls-tree -r --name-only "$1" | grep -E '(^|/)AGENTS\.md$' |
    while read -r f; do git show "$1:$f"; done | wc -lw
}
total cfcc7123   # 127 lines, 851 words (the first cut, before the merge)
total HEAD       # 341 lines, 3096 words (today)

5. Fail the build when it’s over budget. Not done. Run it in CI or a pre-commit hook. I’d set it at 3,000 words, which my own repo fails today (3,096). Good. Someone, probably an agent, will raise the number eventually, and then the growth is a decision in a diff.

#!/usr/bin/env bash
max_words=3000
words=$(git ls-files | grep -E '(^|/)AGENTS\.md$' | xargs cat | wc -w | tr -d ' ')
if [ "$words" -gt "$max_words" ]; then
  echo "AGENTS.md files total $words words (budget $max_words). Delete something first." >&2
  exit 1
fi

A rule that can be a failing test shouldn’t be a paragraph, as long as the test fails when it should (I wrote up five that didn’t).

Mine is at 341 lines today, up from 241 after the last cut. I’d rather post the chart than pretend it stuck.

How I counted: every number comes from git log, git show and wc in the OldMate repo, counting only files named AGENTS.md, in Brisbane time. The 755 is the merge commit b62487b0 at 10:35am on 28 August, which was the upstream tip when I pushed. The quoted prompts, the agent’s suggestions and the 1,170-word draft figure are from my Claude Code session transcripts of 28 August and 23 September.