Most of Your Agent Instructions Are Noise

Anthropic published something in July that should make anyone maintaining an agent stop and look at their own files: they removed over 80% of Claude Code's system prompt for the Claude 5 generation of models, with no measurable loss on their coding evaluations. That prompt was not written carelessly. It was tuned against real evals by the team with the most information about the model, and most of it turned out to be dead weight the moment the model got better.

If that is true of the best-instrumented agent harness in the industry, it is almost certainly true of the CLAUDE.md sitting in your repo, the system prompt in your own agent, and the pile of rules your team has been appending to since the first thing went wrong in production.

I have written both kinds of context. The 12,000-token instruction file that felt responsible and thorough, and the short one that reads like a note to a colleague who already knows how to program. The second one works better now, and the reason is not that brevity is a virtue.

Every rule you write is a claim about the model's failure modes

A constraint in your context is an assertion that the model, left to its own judgement, would get this wrong. That assertion was true when someone wrote it. Nobody goes back and checks whether it is still true.

Anthropic's own example is the comment rule. Claude Code used to say, in effect, default to no comments, never write multi-paragraph docstrings, one short line maximum. That is a sensible guardrail for a model whose unprompted comments were frequently wrong or redundant. It is also wrong for the user who wants documentation, and wrong for the genuinely hard function that deserves a paragraph. The team accepted a bad trade because the alternative was worse. The replacement instruction is one line: write code that reads like the surrounding code, matching its comment density, naming, and idiom. That is not a shorter rule, it is a different kind of rule. It hands the model a way to decide instead of a decision.

The cost of keeping the old one is not just the tokens. It is that your rules start disagreeing with each other. Read a few transcripts of your own agent and you will find requests where the system prompt says one thing, a skill says something adjacent, the repo's context file says a third thing, and the user has asked for something that none of them anticipated.

A capable model will usually work out what you meant. It will just do it after burning attention on a contradiction you created and could have deleted.

Context is an attention budget, not a storage limit

The other half of this comes from Anthropic's earlier engineering piece on context, and it is the part I think engineers underrate because the numbers look generous. A million tokens sounds like room to be thorough.

It is not, because attention degrades before capacity does. Transformers relate every token to every other token, so n tokens produce n² pairwise relationships, and the model's ability to hold all of them sharply gets stretched as the window fills. Models also see far more short sequences than long ones in training, so their attention patterns are simply better practised on short context. The result is a gradient rather than a cliff: recall and long-range reasoning get quietly less precise as you fill the window, long before anything errors.

Treat context as a finite attention budget and the framing of your instruction file changes. The question stops being "is there room for this?" and becomes "is this worth what it displaces?" Almost everything generic fails that test. If a rule describes something the model can see by reading your file system, it is spending budget to tell the model what it already knows.

The move that actually matters is progressive disclosure

The most useful shift I have made is not deleting rules, it is relocating them.

The instinct behind a giant context file is that the agent will never find the information otherwise, so it all has to be present at all times. That was a reasonable fear when the model's only handle on your codebase was whatever you pasted in. It stopped being reasonable once agents got good at going and looking: grep, file reads, skills that load on demand, tools whose definitions are fetched only when relevant.

Claude Code applies this to its own tools now. Some are deferred, meaning the agent has the name but must search for the full definition before calling it, which lets the harness offer far more tools than it could afford to describe upfront. The same structure works for your own material. A verification procedure with six steps does not belong in the file that loads on every turn. It belongs in a skill that gets pulled in when the agent is about to verify something, referenced from your context file in a single line.

What survives in the file itself is the thing an agent cannot discover by looking: the gotchas. The reason all your types live in one module and nowhere else. The migration that must run before the seed script. The service that looks stateless and is not. My own repo's context file is mostly this, and every time I have caught myself writing a paragraph explaining what the folder structure means, deleting it has been the right call.

Design the interface instead of writing examples

Few-shot examples were the first rule of tool usage and they are now the thing I am most suspicious of. The Claude 5 finding is that examples constrain the model to the exploration space the examples describe. Give three examples of how to call a tool and you have quietly told the model that those three shapes are the sanctioned ones.

The better lever is the interface. A status parameter typed as an enum of pending, in progress, and completed teaches usage by existing; the model can read the state machine off the type. A tool description that says exactly one item may be in progress at a time defines the behaviour you want without pretending to be a tutorial. This is the same discipline as designing a library for humans, and it rewards the same things: unambiguous parameter names, one obvious tool per job, and no two tools whose responsibilities overlap enough that a competent engineer would have to guess between them.

That last one is where most agent harnesses fall apart. If you cannot state which of your tools should be used in a given situation, the model will not do better than you, and no amount of prompting fixes an ambiguous surface.

Specs are better when they are code

The related change is what you hand the agent as a reference. Markdown plans and written specs are fine, but they are a lossy encoding of intent in a language full of ambiguity. A failing test suite is a specification with no ambiguity at all. An HTML mockup describes a layout more precisely than three paragraphs about the layout ever will. A function in another codebase that you want ported is a better brief than a description of what that function does.

Prefer artefacts in the languages the model knows best, which are the languages your system is already written in. This also has the pleasant side effect of keeping your references honest, because a test suite that drifts from reality fails, whereas a spec document that drifts just sits there being wrong.

How I decide what stays

The rule I apply to every line of context I own is whether it exists because of a failure I actually observed, on the model I am actually running.

The second question is the one nobody asks. Rules written against a model from eighteen months ago are still being enforced against a model that no longer has that weakness, and the only way to know is to remove the rule and check. Which means you need something to check against. If you have no evals, you have no way to tell a constraint that is holding something up from superstition, and you will keep everything forever because everything feels risky to remove. Start with a handful of tasks you care about and can score, even crudely. The point is not benchmark rigour, it is having any signal at all when you delete something.

For long-running work the same budget thinking applies past the instruction file. Compaction, notes written to disk, and sub-agents that explore with tens of thousands of tokens and return a two-thousand-token summary are all ways of keeping the working window small while the total work stays large. I have written about the storage and retrieval side of that in agent memory, and the principle is identical: the goal is the smallest set of high-signal tokens that gets you the outcome, not the largest set you can afford.

Where this gets uncomfortable

None of this generalises cleanly, and I do not think it should be presented as if it does.

The advice is model-dependent by construction. Anthropic's finding is about their newest models, and if you are running a smaller or older or open-weight model to control cost, the older rules may still be earning their place. Deleting constraints because a blog post said the frontier no longer needs them is how you find out which of your rules were doing something.

There is also a genuine tension between judgement and determinism. Handing the model discretion produces better results on average and less predictable results in any individual case. For a coding agent that is a good trade. For a workflow where every run must be defensible after the fact, average quality is not the metric anyone is being measured on, and I would keep the rigid rules and accept that they cost me something.

What I am confident about is the direction. The instructions you wrote were compensating for a model that has since improved, and nothing in your process notices that on its own. Somebody has to go and delete them.

I write about system design and the senior-to-staff transition every week in Monday BY Gazar on Substack, and I break down architecture and engineering decisions on Gazar Breakpoint on YouTube.

If you are building agents in production and want a second opinion on the design, I do 1:1 mentorship.