CLAUDE.md Configuration Hierarchy

CLAUDE.md tells Claude how your project works — conventions, frameworks, testing patterns, deployment rules. The hierarchy of CLAUDE.md files determines what context Claude has at each interaction. Getting the hierarchy wrong is one of the most common Claude Code misconfigurations.

The Four Levels

Common Mistake: Wrong Level

A team member sets up testing conventions in ~/.claude/CLAUDE.md on their machine. The conventions work for them. Their colleagues don't get the same conventions because user-level files are personal — they're not in git, so no one else sees them.

Diagnosis: use the /memory command to see what context Claude has loaded. If team conventions are missing for new members, the conventions are probably in user-level instead of project-level.

The @import Syntax

Keep CLAUDE.md modular by splitting it into focused files and importing them:

@import ./rules/testing.md
@import ./rules/api-conventions.md
@import ./rules/deploy-flow.md

This keeps each file scannable. A 500-line CLAUDE.md is harder for both Claude and humans than ten 50-line files.

Path-Specific Rules with Frontmatter

For conventions that apply only to certain file types, use .claude/rules/*.md with YAML glob patterns:

---
paths:
  - "**/*.test.tsx"
  - "**/*.spec.ts"
---
All test files must follow the Arrange-Act-Assert pattern.
Use describe blocks to group related tests.
Mock external services with jest.mock at the top of the file.

This rule loads only when Claude is editing a test file. Tokens aren't wasted on irrelevant context, and the rule's instructions don't pollute work in other parts of the codebase.

Path-Specific Rules vs Subdirectory CLAUDE.md

If a convention spans multiple directories — say, "all test files use Arrange-Act-Assert" and tests live in src/__tests__/, frontend/tests/, and backend/tests/ — a path-specific rule is better than three subdirectory CLAUDE.md files. The rule's glob handles all three; subdirectory CLAUDE.md would force you to maintain three copies.

Skills to Develop

1. Use /memory to diagnose what context Claude has loaded.
2. Place team conventions in project-level CLAUDE.md (or root) so they reach every team member via git.
3. Use @import to keep CLAUDE.md modular and scannable.
4. Choose path-specific rules over subdirectory CLAUDE.md when conventions span multiple directories.