Why coding agents ignore your rules

You wrote the rule down and the agent broke it anyway. It is not defiance, and a longer file makes it worse.

August 4, 2026 10 min read

You put the rule in your CLAUDE.md, your .cursorrules or .cursor/rules, or the instructions at the top of the prompt. Never use that library. Always key rate limits by organization. Do not touch this module without a review. And then the agent did the thing you told it not to do, in the first pull request, as if the rule were not there at all. The natural conclusion is that the agent is being careless, or stubborn, or just is not very good. It is none of those. The reason it broke the rule is structural, and once you see it, the fix stops being "write the rule more forcefully" and becomes something else entirely.

Your agent is not being defiant

An agent does not read your rules file the way you imagine a new hire reading an onboarding doc, committing it to memory and consulting it before every action. It reads everything it is given, all at once, as one flat block of text: the system prompt, the rules file, the open files, the retrieved snippets, the conversation so far. Your rule is one sentence in a wall of thousands, and it competes for the model's attention with everything else in that wall, including the code directly in front of it that points the other way.

So the agent did not decide to override your rule. It never weighed your rule against the alternative and chose the alternative. Your rule simply lost, quietly, to nearer and louder signals, and the model produced the most likely continuation of everything it saw. Calling that defiance gives the agent a deliberateness it does not have, and it sends you looking for a fix in the wrong place.

Why a rules file gets overridden

Once you stop treating it as disobedience, the reasons are not mysterious, and a few of them stack together. Only the first has direct research behind it; the rest are the ordinary way a flat, undifferentiated block of text behaves.

Position. Research on how language models use long context, notably the Lost in the Middle work from 2023, found that models use information reliably at the beginning and end of a long context and much less reliably in the middle. That study measured downstream accuracy on document retrieval rather than rule-following, and the effect was not uniform across models, but the implication is hard to escape: a rule sitting in the middle of a large file is in a bad seat, and nothing about writing it in bold or in capital letters moves it to a better one.

Competition. The selection a rules file offers is coarse and static. Modern setups do some of it: Cursor's project rules in .cursor/rules can scope a rule to file globs or offer it to the agent by a one-line description, and a nested CLAUDE.md applies when the agent touches files in its directory. But a glob knows which files a rule sits near, not which decision governs the change being made, and when a description brings a rule in, the model is choosing from a one-line summary of what the rule is about, not from any knowledge of which decision governs this change. So the one rule that should govern this change is still present alongside every other rule that is merely in scope, and the model has to find the needle, which it is not built to guarantee.

Proximity. The code the agent is editing is right there, concrete and specific, and it usually implies its own conventions. When the surrounding code keys rate limits by IP and your rule says key them by organization, the nearby example tends to be a stronger, more immediate signal than a distant line in a file, and the agent follows what everything around it is doing. Which is usually the point. It is also why the common ways of giving an agent context mostly work, right until the change is the one where your specific decision has to override the surrounding pattern.

Staleness. The rule was true when you wrote it and the decision behind it changed three months later, but the file did not. Now the agent is faithfully following a rule you no longer hold, which looks identical, from the outside, to ignoring one you do.

The longer the file, the worse it gets

The instinct, when a rule gets missed, is to add more rules, or to restate the important one with more emphasis, or to write a longer preamble explaining why it matters. Every one of those makes the underlying problem worse. A longer file has more middle for a rule to get lost in, more lines competing for the same limited space, and a lower chance that any single rule lands where the model will actually use it. This is the same reason a bigger context window does not solve the problem: more room to put things is not the same as the right thing being read at the right moment. Past a certain size, a rules file is not an instruction set. It is a junk drawer that everyone keeps adding to and no one can rely on.

A rule is a decision that needs to arrive at the right moment

Here is the reframe that fixes it. The thing you wrote down is not really a rule, in the sense of a standing law that should be recited constantly. It is a decision: for this system, under this constraint, do it this way and not that way. And a decision only matters at one moment, the moment someone reaches the fork it governs. Your "key by organization, not IP" rule is irrelevant on the thousand changes that never touch rate limiting, and it is the single most important thing in the world on the one change that does.

A rules file gets this exactly backwards. It selects by where the code sits, or by what a rule is broadly about, never by which decision governs the change, so the one that binds is always slightly present and never decisively so. What you want is the opposite: the decision that governs this change, surfaced clearly at the moment the agent is making that change, and nothing else competing with it. Not louder. Not longer. Just there, at the fork, when it counts.

How to actually get the rule followed

The fix is not a better-written file. It is to stop relying on the agent to find the right decision inside a flat wall of text, and to instead put the relevant decision in front of it at the point of the change, selected for that change. That is the job Brief does. It is a product navigator: it holds your decisions and the reason behind each one, the real rate limit and why, the real identity model and the incident that set it, the module that is off limits and who it protects, and rather than loading all of them into the context at once, it surfaces the ones that bear on the work at hand, at the moment the agent reaches the fork.

The rules file does not disappear in this setup, and it should not: it shrinks to the one thing a short, always-on file is genuinely good at, a short always-on pointer to Brief, which brief init writes for you. The decisions themselves move into Brief, where they can be selected by which one binds and kept current. So the rule stops being a sentence the agent might notice somewhere in the pile and becomes the specific, relevant decision it is handed exactly when it needs it, and because that decision lives in one place with its reason attached, when it changes you change it once instead of leaving a stale line in a file no one remembered to update.

What this does and does not claim

A few honest limits. Rules files are not useless, and this is not an argument to delete yours. For a small number of stable, always-on instructions, code style, a formatter, a couple of hard prohibitions, a short rules file is exactly the right tool, and it works precisely because it is short and its rules always apply. The failure is specific: it is what happens when a rules file is asked to carry the growing set of product decisions that only apply sometimes, where selection and freshness are the whole game and a flat always-on file has neither. I am also not claiming the agent never genuinely misreads a clear, well-placed instruction; models are imperfect. The claim is narrower and more useful: most of the time your agent breaks a rule, the rule was structurally set up to lose, and no amount of rewriting it fixes a problem that is about when and whether it is read, not how it is worded.

So the next time your agent ignores a rule you know you wrote down, do not reach for a stronger sentence or a longer file. Ask the more useful question: at the moment it made that choice, was your rule actually the thing in front of it, or just somewhere in the pile?

Frequently asked questions

Why does my AI coding agent ignore my CLAUDE.md or .cursorrules? Because the selection a rules file offers is coarse. Modern setups scope rules by file globs, by a one-line description the agent reads (Cursor's .cursor/rules), or by directory (a nested CLAUDE.md), but that tells the agent which files a rule sits near or what it is broadly about, not which decision should govern the change being made. So a rule can sit in the middle of a long file where models use it least, get outweighed by the nearby code that implies a different convention, or be stale. The agent is not choosing to disobey; your rule is losing to nearer and louder signals in the context.

Does writing the rule in bold or capital letters make the agent follow it? Not reliably. Emphasis does not change where the rule sits in the context or whether it is the relevant one for the change being made. The problem is position, competition, and relevance, not wording, so formatting tricks tend to help a little at best and not at all at worst.

Why does adding more rules make it worse? A longer rules file has more middle for any single rule to get lost in and more lines competing for the same limited space, so the chance that the one rule that matters for a given change actually lands where the model uses it goes down, not up. More room to put instructions is not the same as the right instruction being read at the right moment.

How do I make my AI coding agent actually follow my rules? Stop relying on the agent to find the right rule inside a flat file, and instead surface the specific decision that governs a change at the moment the agent makes that change. In practice the rules file stays, but it shrinks to a short always-on pointer to a product context layer such as Brief, which its own setup command (brief init) writes for you; the decisions themselves live in Brief, which holds each one with its reason and supplies the one that binds at the fork, so the instruction is present and unambiguous exactly when it counts and stays current when the decision changes.