How to Reconcile Conflicting CLAUDE.md Layers Before Claude Picks One (2026 Guide)

Start with how many surfaces there are, because most people are running more than they think.

The documentation lists CLAUDE.md locations "in load order, from broadest scope to most specific." A managed policy file, described as holding "Organization-wide instructions managed by IT/DevOps," at a system path — /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL, and a Program Files path on Windows. User instructions at ~/.claude/CLAUDE.md. Project instructions at ./CLAUDE.md or ./.claude/CLAUDE.md.

Then the ones that are easy to forget. Every CLAUDE.md in the directory hierarchy above your working directory is loaded at launch. Every CLAUDE.local.md alongside them is loaded too. Files in subdirectories below you are also discovered — "Instead of loading them at launch, they are included when Claude reads files in those subdirectories." And .claude/rules/ holds as many markdown files as you like.

Six surfaces, plus one per directory level, plus a rules folder. Now the mechanism:

"All discovered files are concatenated into context rather than overriding each other."

Concatenated. Not merged with a winner, not overridden — appended. The order is documented — "content is ordered from the filesystem root down to your working directory," so "instructions closer to where you launched Claude are read last," and within a directory CLAUDE.local.md comes after CLAUDE.md so "your personal notes are the last thing Claude reads at that level" — but order is not precedence. Being read last does not mean winning.

The rules folder makes this explicit rather than implicit:

"Rules without paths frontmatter are loaded at launch with the same priority as .claude/CLAUDE.md."

Same priority. Stated outright. The documentation does not describe a tiebreaker between these layers, and the reason it does not is in the most important sentence in the whole document:

"Claude treats them as context, not enforced configuration."

That is the root of it. These files are not configuration being resolved by a precedence engine; they are text being placed in a prompt. The documentation is candid about the consequence — "Because they're context rather than enforced configuration, how you write instructions affects how reliably Claude follows them. Specific, concise, well-structured instructions work best" — and about the escape hatch: "To block an action regardless of what Claude decides, use a PreToolUse hook instead."

This is worth appreciating rather than complaining about. Other tools do publish precedence orders. GitHub Copilot documents personal instructions as highest priority and organization instructions as lowest. Tabnine documents its admin console as taking precedence over your local guidelines file. Cursor documents team rules outranking project and user rules. Each of those buys determinism and costs you the ability to know, from one file, what the model will see. Claude Code's answer is that everything is context and nothing silently wins, which puts the reconciliation work on you.

The reason it matters more this year is the managed policy layer. An organization can now deploy a CLAUDE.md to every machine, and a recent Claude Code release removed the security approval dialog that a managed claudeMd used to trigger — so it arrives quietly. That file is written by people who do not know your project, it is concatenated with yours, and when it contradicts yours nothing arbitrates. This is the mechanism behind a lot of reports like Claude forgetting house conventions: the convention is in context, and so is something that disagrees with it.

Repeating the rule more forcefully in the project file. Sometimes works, because the documentation does say specific and well-structured instructions are followed more reliably. It also inflates the file, and two emphatic contradictory instructions are still two contradictory instructions.

Putting the rule in CLAUDE.local.md because it is read last. Built on the assumption that last equals winner. The documentation describes ordering, not precedence, and explicitly says files are concatenated rather than overriding each other.

Deleting the user-level file. Effective and expensive. Your personal preferences were not the problem; a genuine conflict between them and a project standard was.

Moving everything into one enormous project CLAUDE.md. This does eliminate cross-file conflicts, and it violates the sizing guidance — the documentation recommends targeting under 200 lines per file, noting longer files "consume more context and reduce adherence." You traded a conflict problem for an adherence problem.

Asking Claude which rule it is following. Reasonable diagnostics, and /context genuinely lists the memory files that loaded while /status names the managed source in force. But asking the model to introspect on an arbitrary choice does not make the choice less arbitrary.

Using a hook. The documentation's own recommendation for hard constraints, and correct — for blocking actions. A hook cannot tell Claude which of two style conventions your team settled on.

The pattern is that all six try to win the conflict. None of them removes it. And a conflict between two imperatives cannot be removed by ranking them, because the information needed to rank them is not in either file.

Three steps: see what is actually loaded, give each layer one job, and remove the reason contradictions accumulate.

Step 1: Enumerate what is really in context

Run /context in a session and read the list under Memory files. This is the authoritative answer, and it is routinely surprising — a CLAUDE.md three directories up that someone added last year, a CLAUDE.local.md you forgot, four files in .claude/rules/ that all load unconditionally. Run /status too and check the Setting sources line, which names the managed source that applies to you, so you know whether an organization file is in play.

Two documented quirks to note while you audit. Imports are real content: CLAUDE.md can pull in other files with @path/to/import syntax, and those are "expanded and loaded into context at launch," so a one-line file can be large. And import parsing "skips Markdown code spans and fenced code blocks" — a path in backticks stays literal, while the same path outside backticks imports the file. If you have documented paths without backticks, you may be importing things you meant to mention.

Also useful: block-level HTML comments are "stripped before the content is injected into Claude's context," which makes them the right place for notes to human maintainers that should not cost tokens.

In a monorepo where other teams' files get picked up, claudeMdExcludes skips them. That is a real fix for a real conflict source, and it is the only one on this list that removes files from context rather than reordering them.

Step 2: Give each layer exactly one job

Now assign scopes so that no two layers can disagree, because each one is talking about something different.

Managed policy holds constraints that are genuinely organizational — security requirements, compliance rules, licensing. Things nobody on your team would argue with. If it holds opinions about frameworks, that is where your conflicts are coming from, and the conversation is with whoever deploys it, not with your project file.

User instructions hold how you personally like to work: response style, your terminal preferences, your shortcuts. Nothing about the project belongs here — that is the most common source of a rule that silently disagrees with a teammate's, and it is the same misplacement that makes making Claude stick to your coding style harder than it should be.

Project instructions hold what is true about this repository: commands, conventions, architecture facts. This is the file that should be shared and reviewed.

.claude/rules/ with paths frontmatter holds anything conditional. This is the important one, because a path-scoped rule cannot conflict with a rule for a different path — they are never both relevant. Moving a rule from an unconditional file into a paths-scoped rule converts a potential contradiction into two non-overlapping statements. Rules without paths load unconditionally at the same priority as your project file, so use the frontmatter whenever the rule is genuinely file-specific.

Skills hold task-specific procedures. The documentation makes the split clean: rules "load into context every session or when matching files are opened," while for "task-specific instructions that don't need to be in context all the time, use skills instead."

One factual note that saves an afternoon: "Claude Code reads CLAUDE.md, not AGENTS.md." If your repository already has an AGENTS.md for other tools, the documented approach is a CLAUDE.md that imports it, so both read the same content instead of two files drifting apart. Two drifting files is the conflict problem in its purest form.

Step 3: Record the decision, not just the rule

After Step 2 you will have a small number of genuine contradictions left — cases where two layers really do disagree about the same thing, and both authors had a reason.

You cannot resolve those by ranking layers. "Use the internal HTTP client" versus "use the standard library client" is unresolvable as two imperatives. It resolves instantly if you know one was written when the internal client was the only one with the required proxy support, and the standard library gained it in a later version.

That information was never in either file, because a CLAUDE.md is a place for imperatives. Which means every conflict you resolve today gets recreated the next time someone writes an imperative without its cause. Auto memory helps a little here — Claude maintains its own store of learnings and corrections per repository, injected each session up to a documented limit of the first 200 lines or 25KB — but that store is written by Claude from your corrections, not a record of decisions your team made and why.

MemoryLake holds the decisions and their reasons outside every instruction file, and answers questions about them over MCP or the API. Your CLAUDE.md files stay short and imperative and load exactly as documented; when two of them disagree, the reason each exists is somewhere you can look it up instead of guessing which layer should win.

Step 1: Create an API key

Generate a key and make your first request in about thirty seconds. Do this before Step 2 above, so you have somewhere to record each conflict as you sort the layers.

Step 2: Upload your first memories

Work through the conflicts from Step 2 and the rules you inherited. For each, write down what was decided, what was rejected, and why. Rules whose reason nobody can remember are the highest-value entries, because those are the ones that will be re-litigated. Supporting documents and files go in the same place.

Step 3: Connect your AI & agents

Give Claude Code, Codex, Devin, and your other agents access over MCP or the API. When a rule looks wrong, the answer to "why is this here" arrives with its reasoning rather than as a louder restatement.

The first change is that your files get shorter. Once reasons live elsewhere, a CLAUDE.md is a list of imperatives, which is what the under-200-lines guidance is asking for and what the documentation says improves adherence.

The second is that most conflicts stop existing rather than getting resolved. A rule scoped with paths and a rule scoped to a different path are never both in context. That is a structural fix, not a ranking.

The third is that the managed policy layer stops being scary. When the organization file holds only genuine organizational constraints and your project file holds project facts, concatenation is exactly what you want — two non-overlapping sets of statements.

The fourth is that the arbitrary-choice sentence stops applying to anything you care about. Claude may still pick arbitrarily between two contradictory rules; you have simply stopped shipping contradictory rules. This is the actual fix for the class of complaint behind Claude Code forgetting project context and behind agents ignoring your instruction files — the instruction was not ignored, it was outvoted by a neighbour.

Run /context before you debug anything. The list of loaded memory files is the ground truth, and it is usually longer than you expect.

One job per layer. Organizational constraints, personal preferences, project facts, conditional rules, task procedures. If two layers can talk about the same subject, they eventually will.

Use paths frontmatter aggressively. A scoped rule cannot contradict a rule for other files. This is the cheapest conflict elimination available.

Keep project files under the recommended size. The documentation targets under 200 lines and notes that longer files reduce adherence. Split by topic into .claude/rules/ rather than growing one file.

Never put project facts in your user file. It is the single most common source of a rule that disagrees with a teammate's and cannot be reviewed.

Wrap paths in backticks unless you mean to import. Import parsing skips code spans, so backticks are the difference between mentioning a file and loading it.

Import AGENTS.md rather than duplicating it. Claude Code reads CLAUDE.md, not AGENTS.md, and two hand-maintained copies of the same conventions will diverge.

Use hooks for hard constraints. The documentation is explicit that these files are context rather than enforced configuration, and that a PreToolUse hook is how you block an action regardless of what Claude decides.

Claude Code documents its instruction files honestly: all discovered files are concatenated into context rather than overriding each other, rules without paths frontmatter load at the same priority as your project file, the whole set is treated as context rather than enforced configuration, and if two rules contradict each other Claude may pick one arbitrarily. There is no hidden precedence engine to learn, which also means there is nothing to appeal to when two of your files disagree.

So stop trying to win those conflicts and stop shipping them instead. Enumerate what actually loads, give each layer one subject so the layers cannot overlap, scope everything conditional with paths, and keep the files short enough to be followed. Then record why each rule exists somewhere outside all of them — because the layer that decides conflicts is not a file path or a load order. It is whether anyone still remembers what the rule was for.