Español

The Rule Your Agent Keeps Ignoring

You wrote the rule down. You put it near the top. You even capitalised it. Your agent broke it anyway, and it will break it again tomorrow. Before you rewrite the sentence for the fourth time, consider that the wording was never the problem.

Emphasis is not a mechanism

The instinct when an instruction gets ignored is to make it louder: bold it, capitalise it, prefix it with IMPORTANT, add "you MUST". This feels like it should work because it works on people. It mostly doesn't work here, and it's worth understanding why.

A rules file is not enforcement. It is context: text loaded into the model's window at the start of a session and competing for attention with everything else in that window. Anthropic's own documentation is blunt about this, describing rules files as context rather than enforced configuration, and noting there is no guarantee of strict compliance. Formatting a line more aggressively doesn't change its status. It's still one line among however many hundred you've accumulated.

Which points at the real variable. If the file is short, your rule is one of thirty things competing. If the file is long, it's one of three hundred. The failure rate you're seeing is a function of that ratio, and shouting adjusts the wrong side of it.

The documented target is under 200 lines

There is a specific number to aim at. The guidance for rules files is to target under 200 lines per file, on the explicit grounds that longer files consume more context and reduce adherence. That second half is the part most people miss. Everyone knows a long file costs tokens. Fewer people connect it to the agent disobeying them.

So the diagnostic is simple, and it inverts the usual reaction:

• If the agent ignores a rule that is clearly written, don't rewrite the rule.
• Check the length of the file it lives in.
• If that file is well past 200 lines, the rule is probably fine and the file is the bug.

This also explains a symptom people find baffling: a rule works fine in a small side project and gets ignored in the big one, with identical wording. Same instruction, different amount of competition.

Cut, don't compress

The wrong fix is to squeeze the same content into fewer words. You keep all the topics and lose the clarity. The right fix is to remove topics from the always-loaded file entirely.

Keep in the rules file only what changes the agent's behaviour on most tasks:

• Conventions you actually enforce — naming, structure, patterns
• Commands — build, test, lint, deploy
• Gotchas — the non-obvious thing that bites everyone once

Move out anything that only matters sometimes. Two mechanisms exist for this. Path-scoped rules live in .claude/rules/ with a paths: frontmatter field, and load only when the agent touches matching files — so your API conventions arrive when it opens the API directory and cost nothing the rest of the time. Skills go further: they load only when invoked or when the agent judges them relevant, which suits multi-step procedures better than a rule does.

Note: One trap worth knowing: splitting a long file into @path imports looks like it should help, but imported files are expanded and loaded at launch alongside the file that references them. You get better organisation and exactly zero context savings. Path-scoped rules and skills are the mechanisms that actually defer loading.

Let the tool do the trimming

You don't have to make the cut decisions yourself. The /doctor checkup includes a trim pass for checked-in rules files, and its heuristic is a good one: it cuts content the agent could derive from the codebase anyway — directory layouts, dependency lists, architecture overviews — and keeps the things it couldn't, which are the pitfalls, the rationale, and the conventions that differ from tool defaults.

That distinction is the whole game. A rules file explaining your folder structure is spending permanent context on something the agent can discover by looking. A rules file saying "this directory is generated, never hand-edit it" is telling it something no amount of looking would reveal. The first is deletable. The second is why the file exists.

/doctor also reports which skills, servers, and plugins are costing you context without being used, and it reports findings before changing anything, so you can run it without committing to its suggestions.

Two failure modes that look like length but aren't

Before you start cutting, rule out two cheaper explanations.

The file didn't load. Run /context and look under Memory files. If the file you're editing isn't listed, the agent has never seen it and length is irrelevant. This catches rules files sitting in the wrong directory more often than you'd expect.

Two rules contradict each other. If two files give conflicting guidance for the same behaviour, the agent may pick one arbitrarily — and from the outside, arbitrary selection is indistinguishable from ignoring you. Nested rules files in subdirectories are a common source, since they're easy to forget. Reviewing for contradictions is worth doing before you conclude the file is merely too long.

The takeaway

A rule nobody reads isn't a rule, it's decoration — and past a certain file length, decoration is what you're writing. The move that actually raises compliance is subtraction: get under 200 lines, push the situational material into path-scoped rules and skills, and let /doctor propose the cuts. Then, if a rule still gets ignored, you'll finally be looking at a rule problem instead of a length problem.