CLAUDE.md Hierarchy

CLAUDE.md is Claude Code's persistent memory: a Markdown file whose contents are injected into every session so the agent remembers your conventions without being reminded. What trips people up is that these files exist at three scopes and combine in a specific way. Understanding that layering is the single most tested idea in this lesson.

The three scopes

Claude Code discovers memory files at three levels, from broadest to narrowest. Each answers a different question about *who* and *where* the rules apply.

• User scope — ~/.claude/CLAUDE.md lives in your home directory, applies to every project you touch, and is never committed. Great for personal preferences; useless to teammates who clone the repo.
• Project scope — CLAUDE.md at the repo root (or .claude/CLAUDE.md) is version-controlled and shared with everyone automatically. This is where team-wide standards belong.
• Directory scope — a CLAUDE.md inside a subfolder (e.g. packages/api/CLAUDE.md) adds conventions that only matter when you work in that part of the tree.

Concatenation, not override

Every discovered file is concatenated into context, ordered broad to specific: user first, then project, then the directory files closest to your working path, with any CLAUDE.local.md appended last at each level. There is no precedence table. If two lines contradict each other, Claude may follow either one — the model treats this content as user guidance, not enforceable configuration.

When CLAUDE.md is not enough

If a rule *must* hold on every run — a blocked tool, a mandatory formatter, a permission policy — guidance in CLAUDE.md is the wrong home because compliance is not guaranteed. Move it to settings.json, which the client enforces regardless of what Claude decides, or wire it into a lifecycle hook that fires at a fixed point.

# CLAUDE.md
- Always run `prettier --write` before finishing.

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{ "command": "prettier --write ." }]
  }
}

Modular organization and diagnostics

Large memory files can be split with @ path imports, which inline a referenced file exactly as if pasted. Note that imports load eagerly — they do not shrink the context Claude sees. Use CLAUDE.local.md for gitignored personal tweaks, and run /memory to *see which files are already loaded*. /memory is a diagnostic; it does not load or activate configuration.

# .claude/CLAUDE.md (project scope, committed)

## Conventions
- Use camelCase for variables, PascalCase for types.
- Every new module ships with a colocated *.test.ts file.

## Imported standards
@./standards/error-handling.md
@./standards/testing.md

# ~/.claude/CLAUDE.md (user scope, NOT committed)
- Every module ships a colocated *.test.ts file.

# CLAUDE.md (project scope, committed)
- Every module ships a colocated *.test.ts file.