What a Long Instruction File Costs You on Every Turn
CLAUDE.md is not a config file you write once — it is re-read on every turn, and it competes with itself. Here is the mechanism behind context rot in instruction and skill files, how to tell whether yours has grown too long, and what to cut first.
Most people treat CLAUDE.md — or AGENTS.md, or a skill file, or whatever your tool calls it — the way they treat a config file: write it once, and it is set up. That mental model is wrong in one specific way, and the way it is wrong explains almost every complaint about long instruction files.
The file is not read once when the session starts. It is part of the input on every turn. Ask a question, get an answer, ask a follow-up — the file went along for all three. A forty-turn afternoon means forty passes. It is not a setup cost. It is a recurring one, and it recurs at the rate you work.
Two things follow from that, and only the second one is really interesting. The obvious one: length is charged repeatedly rather than once. The important one: length is also a dilution problem — the longer the file, the more everything in it has to compete with everything else in it, including your prompt.
Mechanism one: it is re-read, not remembered
There is no memory that persists between turns in the way people imagine. Each turn is assembled fresh: system instructions, your project's instruction file, the conversation so far, the contents of any file that was opened, the output of any command that ran, and finally your actual question. The instruction file is not privileged inside that pile. It is simply earlier text.
So the file has a length, and that length is present on turn one, turn twelve and turn forty. Doubling it does not double a one-off. It doubles something that happens continuously while you work. That is the whole of the first mechanism, and it is arithmetic rather than an argument.
Mechanism two: context rot
"Context rot" is the name that has stuck for the second and more consequential effect. The observation behind it is well documented in public long-context evaluations: the ability to reliably use a specific instruction buried in a large input degrades as that input grows, and degrades faster when the surrounding material is plausible and topically similar rather than obviously irrelevant. It is a slope, not a cliff. Nothing announces itself. The instruction is still there, in the file, in bold — and it is weighted a little less than it was.
That is why a long instruction file behaves worse than a short one even when every line in it is correct. The failure is not that a rule was wrong or badly worded. It is that a rule which is competing against three hundred other lines of your own writing, plus the file currently open, plus the last half hour of conversation, is in a weaker position than one competing against thirty. You wrote the competition yourself, one reasonable addition at a time.
The claim this article is not making
We are not putting a number on any of this, and we are not claiming an outcome. How much a given file length affects a given project is not something we have measured in a way worth publishing, so it is not claimed here. What is described above is a mechanism — recurring inclusion, and degradation with length — and the practical advice below follows from the mechanism, not from a figure.
How to tell whether your file is too long
There is no universal line count, and anyone who gives you one is guessing. What you can do is apply four tests that are specific to your file and your project. All four are things you can run in the next ten minutes.
The briefing test
Would you hand this document to a competent contractor and expect them to read all of it before every single task — not once on day one, but before each task, all week? If the honest answer is no, you are not writing a briefing any more. You are writing a reference manual, and a reference manual belongs somewhere it can be consulted on demand rather than recited constantly.
The relevance ratio
Take the last real task you did. Go through the file and mark every line that mattered for that specific task. Most people find a small fraction. The unmarked lines were not free — they were present, they were competing, and they contributed nothing on that turn. Do this for three different tasks and the lines that never get marked are your candidates.
The enforcement ratio
Count how many lines describe something a machine could check but nothing checks. Those lines are doing the worst possible job: taking up room in every turn while providing no assurance at all. A rule that is only enforced by someone noticing is a preference. It can be moved into a script, a type, or a check, and then stated in one short sentence pointing at it.
The recall test
Add one trivial, harmless, unmistakable instruction at the very bottom of the file — an acknowledgement line, a required comment header on new files, an unusual word in the closing summary. Then work normally and watch for it. If the last line of the file stops landing deep into a session, you have learned something concrete about your file at your length, which beats any general rule of thumb.
Measuring the file itself
Measure in characters, words and lines. Those are stable, tool-independent, and comparable across projects; you get them from `wc -c`, `wc -w` and `wc -l` with nothing to install. Write today's numbers down. The value of the measurement is not the absolute figure — it is watching it move, because instruction files only ever move in one direction unless somebody is looking. Third-party tools that report on instruction-file size across a repository do exist (ccmd.dev is one that comes up in these discussions); we have not evaluated it and are not recommending it, and the point stands with or without a tool.
More like this, occasionally.
Practical write-ups on shipping software with AI assistants — what holds up in a real codebase and what does not. No spam, unsubscribe anytime.
No spam. Unsubscribe anytime.
What to cut first, in order
Work down this list. It is ordered by how little you lose — the first three categories are close to pure subtraction, and for most files they are also most of the file.
- Default behaviour. "Write clean, readable code." "Use meaningful names." "Add error handling." "Follow best practices." These change nothing about the output and they occupy the same room as the line about which directory is generated. Delete them without ceremony.
- Restated public documentation. If a paragraph explains how a well-known framework's routing works, it is competing with material the assistant already has, and it is a maintenance liability the day that framework changes. Link it or drop it.
- Rationale and history. "We chose this because in 2024 we tried the other approach and…" is genuinely valuable and belongs in a design document that a person can open. It does not need to be present on every turn of every task forever.
- Anything said twice. Instruction files accumulate near-duplicates because each addition was written in a hurry by someone who did not re-read the whole file. Two statements of the same rule are not twice as strong; they are two things to keep in agreement.
- Folder-specific material. Auth rules for the admin area, conventions for one package, notes about one build script — all of it belongs in a directory-scoped instruction file next to the code it governs, where it is both closer to the work and absent from every unrelated task.
- Anything mechanisable. Everything the enforcement ratio flagged. Convert it, then replace the paragraph with one sentence naming the mechanism and its path.
- Anything that only matters for one kind of task. Deployment detail, database migration procedure, the release checklist. This is what task-activated skills are for: material that loads when the task matches and is otherwise not present at all.
What to keep, and defend
The lines worth their place share a shape: non-obvious, project-specific, expensive to discover by reading the code, and costly to get wrong. Hazards especially — the tool that silently corrupts files on this machine, the directory that is generated, the command that costs real money, the push that deploys straight to production. Nobody infers those from the source, and each one has a bad day attached to it. Keep them, and keep them near the top.
A quick sort for anything you are unsure about:
| Keep in the always-on file | Move somewhere else |
|---|---|
| Hazards with real consequences | Background on why a decision was made |
| The exact verification command | A tutorial on the framework you use |
| Repository-wide boundaries and no-go areas | Conventions for one folder or one package |
| Facts that contradict a neighbouring project | Anything already true by default |
| One-line pointers to the real reference | The reference itself |
Trimming is mostly relocation, not deletion
Almost none of this material is worthless. The problem was never that it was wrong; it was that it was permanently present regardless of relevance. So most of a trim is a move, and there are four good destinations.
- A directory-scoped instruction file, sitting next to the code it describes. It is read when that area is being worked on, and it has the enormous advantage of being physically close to the thing it is about.
- A skill, loaded when the task matches. This is the design the tooling now pushes you toward, and it is the right one: specialised material has a real cost when it is always present and almost none when it arrives on demand.
- A mechanism — a type, a lint rule, a hook, a script, a template file to copy. The strongest destination, because the rule stops depending on anyone reading anything.
- An ordinary document in the repository, referenced by path in one line. Design history, architecture notes, runbooks. A person opens it when they need it, and so does an assistant that has been told where it is.
A useful target to aim at rather than a rule: the always-on file should fit on roughly one screen of routing — the boundaries, the hazards, the verification command, and pointers to where everything else lives. If it will not fit, that is usually a sign it is two documents wearing one filename.
Re-check it on a schedule
Instruction files grow the way a junk drawer grows: one reasonable addition at a time, each of which made sense on the day, none of which was ever weighed against the file as a whole. Nothing in your toolchain will ever tell you the file has become too long. Put a recurring reminder on it — monthly is plenty — re-run the relevance ratio, re-check the canary at the bottom, and write the new character count next to the old one.
The underlying idea is simple enough to keep in your head: an instruction file is charged on every turn and competes with itself, so length is not neutral and more is not safer. Write it as a briefing rather than a manual, move the specifics next to the work, and give the rules that genuinely must hold something sturdier than prose to stand on.
Scope note: everything above is mechanism and practice. No measurement is reported in this article, and no claim is made about what any particular change will do to your project.
Related reading
Inherited a codebase that grew faster than its conventions?
We build and maintain software for businesses in Waco and across Central Texas, including projects where the AI-assisted parts and the human-written parts stopped agreeing with each other. Tell us what is going wrong.
Talk to Us