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

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"

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.

**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.

**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.

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

4. Format Wars

# Global: Use 2-space indentation
# Project: Use 4-space indentation

**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

**Project CLAUDE.md — project facts + explicit overrides:**

## Project: [Name]
Stack: Next.js 14, TypeScr