Projects that have worked with coding agents for a while accumulate instruction files the way basements accumulate boxes: a CLAUDE.md in the root, one in the home directory, rules per subfolder, plus notes the agent left for itself. Every line was once a reaction to a concrete mistake. Together they eventually add up to something no human reads in one sitting - but the agent does, in every single session.
Except: when two rules in such a file contradict each other, the model picks one - silently, without a warning, without any hint that the other one just stopped having an effect.
What actually happens on contradictions
This is not a quirk of one particular model; it is well documented, including by the vendor. The Claude Code documentation puts it dryly: if two rules contradict each other, the model may pick one arbitrarily. The best practices page adds that bloated instruction files cause rules to simply be ignored.
Research paints the same picture, with numbers:
- The paper ConInstruct tests whether models detect conflicts in instructions. The best ones do surprisingly well, with F1 scores up to 91.5 percent. The catch: they almost never say so. Hardly any model points out the conflict or asks which rule should apply.
- The IH-Benchmark measures how reliably 37 models respect instruction hierarchies - compliance ranges from 98.2 all the way down to 20.5 percent.
- OpenAI's paper The Instruction Hierarchy describes why models need to learn priorities between instruction sources in the first place. The point that matters for everyday work is the inverse: two lines in the same file sit on the same level of the hierarchy. For that case there is no defined precedence - the model has to guess.
How that guessing turns out is often decided by the rule's position in the file. And the more consistently a model resolves such conflicts, the less the contradiction shows: where behavior used to flicker between runs and draw attention to itself, today the same rule loses reliably, in every session - and nothing looks like a problem anymore.
Why position carries so much weight
That a rule's placement decides its fate fits a well-known finding: Lost in the Middle showed back in 2023 that language models use information at the beginning and end of a context far more reliably than information in the middle. Anthropic describes the mechanism behind it in Effective context engineering for AI agents: models have a limited attention budget, and every additional token dilutes it. The recommendation there is the guiding principle for everything that follows: the smallest set of tokens that produces the desired behavior.
A grown instruction file violates both at once. It is too long, so half the rules end up in the dead middle. And it contains contradictions, so position decides which half wins.
The tutorial: six steps to clean up
Step 1: Take inventory
First find out what the agent actually reads. In Claude Code, /context shows which files are loaded in the session. The documentation lists the layers: an organization-wide file, the personal one in the home directory, the project file, local notes, rule files under .claude/rules/, and the notes the agent writes for itself. Grown projects add files in subdirectories that only load once work happens there. Only when that list is complete do you know what you are actually talking about.
Step 2: Read relationally, not sequentially
The central move: don't read the files top to bottom, read them by topic. Collect every rule that concerns the same thing - tests, formatting, directories, language - regardless of where it sits and how it is phrased. Then ask one question for every pair: can both be true at the same time? This check needs no model and no test run, just an afternoon and honesty. Conflicts like to hide behind differing vocabulary: "comments", "documentation" and "annotations" can mean the same thing and still carry three different rules.
Step 3: Cut until it hurts
For every remaining line, the question from the best practices: would the agent make mistakes without this line? If not, delete it. Everything the model can read from the code itself - directory layout, dependencies, standard language conventions - costs attention without buying anything. The documentation names a target of under 200 lines per file. Watch the altitude while you cut: rules concrete enough to verify ("2-space indentation"), but not so granular that they turn into a brittle collection of special cases.
Step 4: One topic, one place
Every topic gets exactly one heading and one vocabulary. An exception belongs in the same sentence as its rule ("every function needs a test, except under scratch/"), not three paragraphs further down as its own instruction - phrased separately, rule and exception are two competing rules as far as the model is concerned, and position decides which one wins.
Step 5: Sort by bindingness
Instruction files are context, not configuration - the model tries to follow them, nothing more. For anything that must hold always, prose is the wrong tool. Claude Code offers hooks for that, executed deterministically no matter what the model decides. Knowledge that is only needed sometimes belongs in skills or path-scoped rules that load only when relevant. What remains is the small core that truly belongs in every session - and that core is then short enough to be followed.
Step 6: Treat it like code
An instruction file nobody maintains rots like code nobody maintains - just more quietly. If the agent keeps getting the same thing wrong despite a rule, the first suspect is not the model but the file: too long, too vague, or contradicting itself. Review changes like code changes: does the behavior actually shift? And repeat step 2 at intervals, because every line hastily added after an incident is a candidate for the next contradiction.
Conclusion
The uncomfortable part of this topic is not that models handle contradictions badly - it is that they have become so good at resolving them noiselessly. Research shows models that detect conflicts and stay silent anyway, and practice shows rules that apply or don't depending on their line number. Waiting for the agent to complain is not a strategy. Reading the file relationally costs an afternoon. Silently losing a rule you thought was in force costs more.
Sources
- Claude Code: How Claude remembers your project - official documentation on CLAUDE.md, rules and auto memory
- Claude Code: Best practices - official guidance on instruction files, hooks and context
- Anthropic: Effective context engineering for AI agents - attention budget, rule altitude, minimal context
- Liu et al.: Lost in the Middle: How Language Models Use Long Contexts - position bias in long contexts (TACL 2023)
- Wallace et al.: The Instruction Hierarchy - why models need priorities between instruction sources (OpenAI, 2024)
- IH-Benchmark: A Conflict-Centered Benchmark for Instruction-Hierarchy Robustness - hierarchy compliance across 37 models
- He et al.: ConInstruct: Evaluating LLMs on Conflict Detection and Resolution - models detect conflicts but rarely report them
Top comments (0)