The Limits of Telling: Why Instruction Files Don't Do What You Think

You write it down, so it will happen. That's the quiet assumption behind every instruction file — the CLAUDE.md, the AGENTS.md, the .cursorrules, the carefully worded system prompt. Put the rule in the file, and the agent will follow it. It's a reasonable belief. It's also, in a specific and important way, wrong.

Instruction files are the most natural way to steer an AI agent, and they're worth having. But they're weaker than they feel, and the ways they fail are quiet — no error, no warning, just an instruction that didn't take. Knowing those failure modes is the difference between fighting your instruction files and designing around them. Here are the limits worth understanding.

A rule is a suggestion, not a switch

When you write a line in a config file, it executes. When you write a line in an instruction file, it doesn't — it becomes one more piece of input the model weighs against everything else in front of it. "Always do X" isn't a switch you flipped to on. It's a strong suggestion competing with the code on screen, the user's latest message, the shape of the task, and the model's own instincts.

Most of the time the suggestion wins, which is exactly what makes this dangerous. It works often enough that you stop checking — and then on the request where the context is crowded or the task pulls hard in another direction, the rule quietly loses, and nothing tells you it happened. There's no exception thrown when an instruction is ignored. The first sign is usually the wrong output itself.¹

More rules, less obedience

The intuitive fix for an ignored instruction is to add another instruction. Make it bolder. Put it in all caps. Add a second rule reinforcing the first. This is the trap.

Every rule you add competes for the same finite attention as every other rule. A tight file where five things matter gets those five things followed. A sprawling file where eighty things matter gets a rough average — and your critical rule is now sharing the stage with seventy-nine others, most of which don't matter nearly as much. Instruction files don't scale by accretion. Past a certain size they're followed worse, not better, and the rule you cared most about is the one drowning. Length reads as thoroughness to the author and as noise to the model.²

They can't verify themselves

An instruction file can say "always run the tests before committing." It cannot run the tests. It can say "never push to main." It cannot stop the push. A file describes desired behavior with no power to confirm the behavior happened.

This is the deepest limitation, because it means compliance is invisible by default. The instruction and its own enforcement live in different worlds — the file asks, and then it's blind to whether the asking worked. You find out a rule was skipped the same way you find out anything went wrong: after the fact, by looking. Anything you genuinely need to be true cannot be left to a sentence that has no way to check itself.³

They compete with what the model already believes

A model shows up to your repo with priors — an enormous number of examples of how things "usually" work. When your instruction agrees with those priors, it sails through. When it contradicts them, it's in a fight, and it doesn't always win.

Tell a model that your framework's API differs from the one it learned, that the convention here is the opposite of the common one, that this project does the unusual thing on purpose — and watch how often it drifts back to the familiar pattern anyway. The instruction is right there in the file. The training data is right there in the weights, and there's a great deal more of it. A single line asking the model to unlearn a deeply reinforced habit is bringing a note to a tug-of-war.

They drift out of sync with reality

An instruction file is written once and read forever, while the thing it describes keeps moving. The command you documented gets renamed. The directory you pointed at gets restructured. The rule that made sense three months ago now describes a repo that no longer exists.

A stale instruction is worse than a missing one. A missing instruction leaves the model to reason from what it can actually see. A wrong instruction actively steers it toward a reality that isn't there — and the model has no easy way to know the file is lying, because it trusts the file the way you hoped it would. The one time a bad instruction commands full obedience is the one time you wish it wouldn't.

So what are they good for

None of this means throw the files away. It means using them for what they're actually good at, and not for what they can't do.

Instruction files are for orientation, not enforcement. They're the fastest way to tell a model where things are, what this project values, which conventions to prefer, how to get its bearings. That's real, and it's worth doing well: keep the file short, keep it current, and spend your rules on the things that shape judgment rather than the things that must never vary.

For anything that must never vary, stop writing rules and build a mechanism. A hook that blocks the commit enforces what a sentence about committing only requests. A test that fails loudly beats a paragraph asking for correctness. CI that rejects the push does what "never push to main" cannot. The instruction file asks; the mechanism enforces — and the difference between asking and enforcing is the difference between a rule you hope holds and a rule that can't break.⁴

Write the file. Keep it lean. Then, for everything that actually matters, put a guardrail where the words used to be.

❯ enforce() > ask() ✓

Sources

¹ Anthropic, Best practices for Claude Code — adherence is something you “tune… by adding emphasis,” and bloated files cause Claude to ignore instructions.

² Anthropic, Best practices for Claude Code — “keep it concise… bloated CLAUDE.md files cause Claude to ignore your actual instructions,” and performance degrades as context fills.

³ Anthropic, Best practices for Claude Code — “the trust-then-verify gap… if you can’t verify it, don’t ship it,” and Define success criteria and build evaluations.

⁴ Anthropic, Best practices for Claude Code — “unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens,” and Automate actions with hooks.