An AGENTS.md line is worth its surprisal

A line in an AGENTS.md earns its place if it states a choice the model can’t infer or a failure the model can’t see.

I learned that in two steps. First I found out that most of my file did nothing. Then I found out that a few of its lines were doing real harm.

Most of the file did nothing

In July the AGENTS.md of localvoxtral kept growing. I didn’t know the code well, so everything went in: where each module lived, how to build, how to test. I thought it was why my agents did good work on the repo.

On 21 July it passed 32 KiB, and Codex silently truncates an AGENTS.md past that size. By 5 August the file was 949 lines and 68 KB, so most of it never reached Codex. An agent auditing the docs flagged the truncation two weeks later. In those two weeks, nothing had broken.

The agents were doing well because they could explore the repo, not because of the file.

So extra lines looked harmless. Anthropic’s best practices for Claude Code give the usual reason to cut them anyway: “Claude’s context window fills up fast, and performance degrades as it fills.” But Opus 5.5 has a context window of a million tokens, and a thousand lines barely register. If context were the whole cost, I’d have stopped worrying there.

A few lines did real harm

The file said the repo was built and tested on my Mac, as if there were no other way. The agents took it at its word.

In one week in September they made about 1,090 remote builds on the Mac, 440 of them full test-suite runs. My MacBook was always hot. With one or two agents that was fine. With many at once, CI jobs queued for the one machine: one in ten waited six minutes or more, and the worst waited 33. These were the best models available, and not one of them asked whether the Mac needed to do any of it.

I was encouraging the models to thrash my Mac. They didn’t even need to. I just told them to.

When I rewrote those rules, the Mac started running only the tests a change touches, and the full suite moved to a hosted runner. That took about 680 minutes a week of automatic work off the Mac, and nine in ten CI jobs there now start right away. The new rule is almost word for word a line in Anthropic’s example CLAUDE.md: “Prefer running single tests, and not the whole test suite, for performance.” I got there by overheating my laptop.

The real cost is exploration

Surprisal is how unexpected something is to a model. A line the model would have followed anyway has almost none. On a small greenfield Next.js and FastAPI app, Fable 5.1 passed every check on three tasks with the file deleted, because every stack convention in it was already its default.

At best, a line like that is wasted. At worst it reads like a decision, and the agent stops looking for a better one. That’s the real cost of an extra line: not the tokens, but the exploration it switches off.

So keep what the model can’t know, and leave the rest to exploration. Three lines that stayed in localvoxtral’s file, abridged:

- On the Mac, run only the suites your change touches. Never run the
  full suite there: the PR's hosted `build-test` runs it on every push.
- Never read a child process pipe with `FileHandle.availableData`. It
  raises an uncatchable ObjC exception on a descriptor error and aborts
  the app (#60).

Every agent loads this file, and Codex silently truncates it past 32 KiB
(`AgentsGuideSizeTests` enforces the budget).

The first is a choice the model can’t infer. The second is a failure it can’t see: availableData looks like any other Foundation API until it takes the app down. The third is a fact about the tools themselves.

To find out what yours is doing, delete one section of your AGENTS.md, run a real task, and diff the result.