DEV Community

Olivia Craft
Olivia Craft

Posted on

Your CLAUDE.md Files Are Fighting Each Other (And How to Fix It)

#claudeai #aitools #claudecode #productivity

When your Claude Code agent starts doing the wrong thing, the first suspect is always your CLAUDE.md.

But there's a conflict most developers miss: your global CLAUDE.md and your project-level CLAUDE.md can actively fight each other — and Claude will silently pick one, or blend both in unpredictable ways.

Here's what that looks like in practice:

~/.claude/CLAUDE.md          # global: "always use TypeScript strict mode"
./CLAUDE.md                  # project: "use loose types for prototyping"
Enter fullscreen mode Exit fullscreen mode

You get inconsistent behavior. Sometimes strict. Sometimes loose. The agent acts like it's having a bad day, but it's just confused by contradictory instructions.

Why This Happens

Claude Code loads CLAUDE.md files from multiple locations:

  1. Global (~/.claude/CLAUDE.md) — applies to every project
  2. Project root (./CLAUDE.md) — project-specific overrides
  3. Subdirectory (./src/CLAUDE.md) — scoped to that folder

When these conflict, there's no explicit "last one wins" rule you can count on. Claude tries to reconcile them, which means sometimes it merges, sometimes it overrides, sometimes it ignores one silently.

The 5 Most Common Conflict Patterns

1. Style Contradictions 

# Global CLAUDE.md
Always write concise, minimal code. No comments unless critical.

# Project CLAUDE.md  
Document every function with JSDoc. Explain reasoning in comments.
Enter fullscreen mode Exit fullscreen mode

Result: Agent alternates between documented and undocumented code within the same session.

2. Tech Stack Contradictions 

# Global CLAUDE.md
Prefer functional programming. Avoid classes.

# Project CLAUDE.md
This is an OOP codebase. Use classes and inheritance patterns.
Enter fullscreen mode Exit fullscreen mode

Result: Agent writes hybrid code — functional methods inside classes, or breaks existing patterns.

3. Scope Leaks 

# ~/.claude/CLAUDE.md
When in doubt, ask before making changes.

# ./CLAUDE.md
Move fast. Make the change, then explain it.
Enter fullscreen mode Exit fullscreen mode

Result: Agent hesitates unpredictably. Sometimes asks. Sometimes acts. No reliable behavior.

4. Format Wars 

# Global: Use 2-space indentation
# Project: Use 4-space indentation
Enter fullscreen mode Exit fullscreen mode

Result: Mixed indentation across files generated in the same session.

5. Memory Bleed

Your global CLAUDE.md accumulates instructions over months. Older rules about past projects start leaking into your current one.

The Fix: Layered Ownership Model

The cleanest structure that eliminates conflicts:

Global CLAUDE.md — identity only, no project opinions:

## Agent Identity
- You are a senior developer helping me ship production code
- Be direct. Skip unnecessary explanations.
- When uncertain about scope, ask one clarifying question.

## Universal Rules
- Never commit secrets or API keys
- Always run linters before reporting "done"
- Prefer reversible changes
Enter fullscreen mode Exit fullscreen mode

Project CLAUDE.md — project facts + explicit overrides:

## Project: [Name]
Stack: Next.js 14, TypeScript strict, Prisma, Postgres

## This project overrides global settings:
- Use 4-space indentation (eslint enforced)
- Classes are preferred here (legacy codebase)
- Document all public functions with JSDoc

## Project-specific rules
- Never touch /legacy/* without explicit confirmation
- DB migrations go in /prisma/migrations only
- API routes follow /app/api/[resource]/route.ts pattern
Enter fullscreen mode Exit fullscreen mode

Key principle: Project CLAUDE.md should explicitly acknowledge it's overriding global settings when it is. Don't let Claude guess.

Diagnostic: Is Your CLAUDE.md Conflicting?

Run this check:

# See all CLAUDE.md files Claude will load for your project
find ~ -name "CLAUDE.md" -not -path "*/node_modules/*" 2>/dev/null

# Check for common conflict keywords
grep -h "always\|never\|prefer\|avoid\|use\|don.t" ~/.claude/CLAUDE.md ./CLAUDE.md 2>/dev/null | sort
Enter fullscreen mode Exit fullscreen mode

If you see opposing instructions for the same topic — that's your conflict.

Quick Fixes

Option 1: Scope your global CLAUDE.md narrowly
Keep it to agent behavior and universal safety rules. Move all project opinions into project-level files.

Option 2: Add an explicit precedence header

# ./CLAUDE.md
<!-- This file takes precedence over global CLAUDE.md for this project -->
Enter fullscreen mode Exit fullscreen mode

Not a hard guarantee, but it helps Claude weight the project file higher.

Option 3: Use a rules structure with clear sections
Organize both files so Claude can easily identify what domain each rule covers — reducing the surface area for conflicts.

If you're maintaining CLAUDE.md files across multiple projects, at some point the global one becomes a liability. A structured rules pack with pre-separated global and project layers is worth the investment.

→ CLAUDE.md Rules Pack — 47 production-tested rules, organized by layer (global, project, subdirectory). Drop-in structure that eliminates the conflict problem without rewriting from scratch.

Also useful: Cursor Rules Pack — same layered approach for Cursor IDE.

Found a conflict pattern not listed here? Drop it in the comments — I'll add it to the next version.

Top comments (0)