Delete one section from your agent instructions file and rerun last week’s tasks. If the results look the same, that section was decoration, and you’ve been paying for it on every task since someone wrote it.
That’s the method, and I think it’s the only honest way to decide what belongs in the file. Opinions about what an agent needs to know are cheap. A section either changes what the agent does or it doesn’t.
The file is a recurring charge
The file goes by CLAUDE.md, .cursorrules, .github/copilot-instructions.md, or whatever your tool of choice reads at startup. The mechanics are the same under every name. The file gets loaded into context at the start of the session, before the agent has looked at a line of code. Claude Code does it, Codex CLI does it, the Copilot coding agent does it.
So a 2,300-token file is 2,300 tokens on a one-line typo fix and 2,300 tokens on a three-hour refactor. The money is the small part. What I’d worry about is attention. Every paragraph of background sits next to the one rule you really needed followed, and the agent has no way to tell which of the two you meant. I’ve written before about treating the context window as a budget, and this file is the line item nobody audits, because it was written once and it “seems helpful”.
These files grow the same way wikis do. Someone adds a paragraph after an agent does something annoying. Nobody removes one.
What the repository can’t say for itself
An agent can read your code. It can list directories, open the package manifest, read the tests, and work out the architecture faster than your overview paragraph explains it. Anything it can find that way doesn’t need restating.
What it can’t find is the stuff that lives in people’s heads:
- The exact command that checks a change, and the faster one for a single test. A repo with four plausible test commands will get the wrong one run. (If that command doesn’t exist yet, fix the repository first.)
- Directories that must not be edited by hand, and what to do instead. Generated code looks exactly like code.
- Conventions with no tool behind them. Money as integer cents, a naming rule for migrations, which of two HTTP clients is the old one.
- Actions that need a human first, like adding a dependency or touching a schema.
Here’s a starter file. Six sections, each one a place for facts and nothing else.
# CLAUDE.md
## Commands
- Install: `make setup`
- Check a change (lint, types, unit tests): `make check`
- Run one test file: `make test FILE=path/to/test_file.py`
- Do not run the full integration suite locally. CI runs it.
## Do not edit
- `generated/`: built from `schemas/`. Change the schema, then run `make generate`.
- `migrations/`: existing files are frozen. Add a new one with `make migration NAME=...`.
## Conventions no tool enforces
- Money is an integer number of minor units plus a currency code. Never a float.
- Public functions in `api/` take and return typed models, not dicts.
## Where things live
- `api/` request handlers, `core/` business rules, `adapters/` third-party clients.
- New third-party calls go in `adapters/`, never in `core/`.
## Ask before
- Adding a dependency.
- Changing anything under `schemas/` that renames or removes a field.
## Definition of done
- `make check` passes.
- New behavior has a test that fails without the change.
- The diff touches only files the task needs.
No history, no values statement, no “we care about clean code”. The agent was going to write clean-ish code anyway.
Take out one section and rerun
The test is an ablation. Pick a fixed set of tasks, ideally real ones you’ve already closed: 20 to 30 small changes with a test that judges each. Run the agent over all of them with the full file. That’s your baseline. Then run again with one section removed, then put it back and remove the next.
Two outcomes get recorded per task. Did it complete, meaning the tests pass. And did it keep the rules, which you check mechanically: a diff that touches generated/ is a violation whether or not the tests are green.
Agents aren’t deterministic, so a one-task swing means nothing. Run each configuration two or three times if you can afford it, and only believe gaps that survive the repeat. With six sections and 30 tasks, a single pass is 210 runs counting the baseline. It can run unattended overnight, and you’d do it maybe twice a year.
The scorecard is a CSV with one row per section:
section,tokens,tasks_completed_without,rule_violations_without,tasks_affected,verdict
Commands,,,,,
Do not edit,,,,,
Conventions no tool enforces,,,,,
Where things live,,,,,
Ask before,,,,,
Definition of done,,,,,
verdict takes one of three values: keep, move to a linter, delete.
Six sections out, one at a time
To show how the numbers read, picture a payments team at Tollgate Pay whose instructions file has kept growing since the day someone wrote it. Tollgate Pay is fictional, and so is its 2,300-token file. They take 30 closed tickets as the task set. With the full file, the agent completes 23.
| Section removed | Tokens | Completed (of 30) | What changed | Verdict |
|---|---|---|---|---|
| Project history | 520 | 23 | Nothing | Delete |
| Coding philosophy | 610 | 23 | Nothing | Delete |
| Style rules | 570 | 23 | Import order wrong in 3 diffs | Move to a linter |
| How to run tests | 180 | 15 | Agent guessed commands, 8 tasks lost | Keep |
Never edit generated/ |
60 | 23 | Rule broken twice | Keep |
| Money conventions | 360 | 19 | Floats for amounts in 4 tasks | Keep |
The two biggest sections did nothing anyone could measure. The 180 tokens on running tests were carrying eight tasks. The style rules did change behavior, but a formatter in make check does the same job for zero tokens and never forgets. The file ends at 600 tokens.
The generated/ row is the one I’d look at longest. Completion didn’t move at all, because the tests still passed with a hand-edited generated file. If Tollgate had only counted green builds, a 60-token rule that prevents a nasty class of bug would have looked like dead weight. That’s why the rule checks sit beside the tests, as their own column.
Where the test misleads you
A section can score zero because your task set never exercises it. “Ask before adding a dependency” won’t show up if none of the 30 tasks tempts the agent to add one. Before deleting a rule, check whether any task could have broken it. If none could, add a task that does, or keep the rule and mark it untested.
And the scorecard goes stale. A model upgrade can make a section redundant, or make a missing one matter. Rerun it when the model changes and whenever someone proposes adding a paragraph. The price of admission for new text is a task that fails without it.