Agent configuration files (AGENTS.md, CLAUDE.md and equivalents)

Read these first

• The extensibility landscape

What you will know

• Write a config file that meaningfully improves agent behaviour in a repo

  A reviewer should be able to identify a task where the agent makes a materially better choice because of the added guidance.

• Populate the file with build commands, conventions, and invariants, then verify each instruction against a concrete agent task

  Useful entries are precise enough to execute or test; vague preferences increase prompt cost without reliably changing outcomes.

• Show a before and after on a real task

  Use the same repository state and task so the comparison isolates the instructions rather than differences in code, tools, or prompting.

• Measure the prompt and latency cost of loading the file on every session

  Repeated context consumes tokens even when irrelevant, and oversized files can crowd out task-specific information.

• Reproduce a failure caused by stale or conflicting guidance, then patch the config and add a regression check

  Precedence differences, obsolete commands, and undocumented exceptions can make an agent follow instructions that humans no longer recognize as valid.

Chapters

1. 1

   An entry that restates a default bills without changing anything

   'Prefer clean, readable code' and 'write tests for new behaviour' are already how the model behaves, so three weeks later nobody can name a task that went differently. Compare that with 'run one test file with `pnpm vitest run path/to/file.test.ts`', which changes a decision on the first task that needs it. Rank entries by whether they are precise enough to execute or to check, not by whether they sound reasonable.

   Read chapter
2. 2

   Last week's transcripts versus this week's proves nothing

   Between the two weeks the repository moved, the tasks changed and different people wrote the prompts, so the comparison credits the file with everything else that happened. The honest form runs the same task on the same commit, once with the file and once without, and reads the diff in what the agent actually did. That is also how you check a ranking of entries instead of asserting it.

   Read chapter
3. 3

   Three thousand always-loaded tokens displace the task's own evidence

   Pricing the tokens is arithmetic that comes out negligible and measures the one cost that does not matter. What a resident config buys is displacement: the share of the working context it holds at the moment the agent is deepest into a task, competing with file contents, tool output and history. Measure the latency side as well — time-to-first-token on every session, how far prefix caching makes a stable file effectively free after the first call, and what that saving costs you the moment someone edits the file. Then establish whether the file is implicated when long sessions start losing earlier context, using the paired run from the previous chapter, and set a size rule that means something.

   Read chapter
4. 4

   A command nobody executes stays wrong for four months

   The file says `yarn test`; the repo moved to pnpm in the spring; traces show the agent hitting command-not-found, concluding the environment is broken and finishing without running tests. Correcting the line is half a fix — add a check that fails when a command named in the config cannot run in a clean checkout. The deeper version is an instruction written for a workflow that no longer exists.

   Read chapter
5. 5

   Two rules for one action, and the model arbitrates differently each run

   'Never edit files under `generated/`' and, forty lines later, 'regenerate and commit the client in `generated/api/` after schema changes' both apply to the same action with no stated relationship. Behaviour then varies run to run, and no amount of emphasis settles it. Resolve the conflict in the text by making the general rule state its exception, then add a regression check that reproduces the original failure.

   Read chapter
6. 6

   Some invariants belong in the runner, not in the file

   An instruction phrased for a manual workflow the tooling has since replaced cannot be followed as written, and strengthening its wording only stacks confidence on top of the mismatch. When the failure is a destructive backfill against production, no standing sentence is the remedy: the guarantee moves into the runner's staging-by-default mode, a pre-execution guard, or a CI gate that fails the change — enforcement the agent cannot decline to read or reinterpret. Here you learn to separate the entries that only ever needed to be text from the ones whose enforcement has to leave it, and what each choice costs in maintenance and friction.

   Read chapter
7. 7

   An imperative with concrete nouns is still a preference

   'Always prefer composition over inheritance' passes any grammatical filter and changes nothing, which is how a reviewed file fills with well-formed lines nobody can attribute a behaviour change to. Write the standard around attributability instead: name the task where the entry changes a decision, and the check that would notice if it stopped. Then decide what catches an entry that passes review and turns out worthless.

   Read chapter