Claude Code CLAUDE.md: Find and Fix Conflicts

Updated 6 November 2026 · Standard formula, shown below

When you run Claude Code and get an error about a conflicting CLAUDE.md file, it means multiple instruction files are trying to set the same setting or rule in different ways. The fix is to locate every CLAUDE.md that applies to your project, compare their contents, and merge or remove the duplicated directives so only one clear instruction remains.

What CLAUDE.md Files Do

CLAUDE.md is a plain-text file that Claude Code reads to learn how you want it to behave in a specific project. You can put coding style rules, allowed commands, project structure notes, or any other guidance in it. Claude Code looks for these files in a specific order, and when two files define the same thing differently, it flags a conflict instead of guessing which one you meant.

Where Claude Code Looks for CLAUDE.md

Claude Code checks multiple locations, from the most general to the most specific. A conflict happens when a setting appears in more than one of these:

User-level – a global CLAUDE.md in your home directory that applies to every project.
Project-level – a CLAUDE.md in the root folder of your current project.
Subdirectory-level – CLAUDE.md files inside subfolders, which apply only to that part of the project.
Imported files – any file you explicitly reference with @path/to/file inside another CLAUDE.md.

When two of these define the same rule (for example, “always use tabs” vs. “always use spaces”), Claude Code cannot know which you want and reports a conflict.

How to Find the Conflicting Files

You don’t have to guess where the conflict is. Follow these steps to pinpoint it:

Run claude in your project directory and look for the warning or error message. It usually names the two files involved.
If the message doesn’t name files, search your project for every CLAUDE.md file:

find . -name "CLAUDE.md" -not -path "*/node_modules/*"

Also check your home directory for a user-level file:

ls ~/.claude/CLAUDE.md

Open each file and look for duplicate keys or directives. Common ones include language, style, commands, and permissions.

How to Fix the Conflict

Once you know which files are fighting, choose one of these fixes:

Merge the instructions – combine the unique parts of both files into one, keeping only the version of the conflicting rule you actually want.
Remove the duplicate – if one file repeats a rule that already exists in a higher-level file, delete the duplicate line from the lower-level file.
Use a single source of truth – keep the rule in only one file (usually the project root) and use @import to pull in shared content if needed.

After editing, restart Claude Code and run a simple command to verify the conflict is gone. If you still see the error, check that you didn’t leave two copies of the same directive in different files.

Common Mistakes That Cause Conflicts

Most conflicts come from a few repeatable mistakes. Knowing them helps you avoid the problem entirely:

Copy-pasting the same block into multiple CLAUDE.md files without adjusting it.
Using both a user-level and a project-level file for the same rule, thinking the project one overrides the global one. It doesn’t – it conflicts.
Editing a file in a subfolder when you meant to edit the root file, creating an accidental duplicate.
Forgetting to remove an old file after moving a project or renaming a folder.

Preventing Future Conflicts

Good organization prevents most conflicts. Keep these habits in mind:

Put global rules (like “always use tabs”) only in the user-level file.
Put project-specific rules only in the project root CLAUDE.md.
Use subdirectory files only for rules that truly apply to that subfolder.
When you import a file, don’t also paste its contents into the importing file.
Review your CLAUDE.md files periodically to remove outdated or duplicate lines.

What Happens If You Ignore the Conflict

If you ignore the error and continue, Claude Code may pick one version arbitrarily or refuse to run certain commands. That can lead to inconsistent behavior – sometimes it follows one rule, sometimes the other, depending on which file it reads first. Fixing the conflict is the only way to get predictable, reliable instructions.

Frequently Asked Questions

How do I know which CLAUDE.md file takes priority?

Claude Code reads them in a specific order, but when two files define the same rule, it doesn’t pick a winner – it reports a conflict. To avoid this, don’t repeat the same directive in multiple files. If you must have a rule in two places, make sure they say exactly the same thing, but even then it’s safer to keep one copy.

Can I use environment variables in CLAUDE.md?

Yes, you can use environment variables in your instructions. But if you set the same variable in two different files with different values, that’s a conflict. Use only one place to define each variable.

Does the order of files matter for non-conflicting rules?

Yes. For rules that don’t conflict, Claude Code merges them, and the more specific file (like a subdirectory one) can add to the more general one. But if a rule is repeated, it’s a conflict regardless of order.

What if I have a CLAUDE.md in a subfolder that conflicts with the root one?

The same conflict rules apply. Decide which level should own that rule. Usually the root file should contain project-wide rules, and the subfolder file should only contain rules specific to that subfolder. Remove the duplicate from one of them.

Can I disable CLAUDE.md entirely?

There is no official way to disable it completely, but you can rename the files or move them out of the project directory. However, that removes all your custom instructions, so it’s better to fix the conflict than to disable the feature.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.