CCA-F
Sign inStart Free

CLAUDE.md Configuration Hierarchy

Core

Configure CLAUDE.md files with appropriate hierarchy, scoping, and modular organization · Difficulty 2/5

0%
claude-codeconfigurationclaude-mdhierarchy

Explanation

Claude Code reads project instructions from multiple configuration sources with a specific precedence order.

Configuration Sources

  1. Project CLAUDE.md: Root-level CLAUDE.md or .claude/CLAUDE.md -- loaded for every conversation
  2. Directory CLAUDE.md: Subdirectory CLAUDE.md files -- additive context when working in those directories
  3. User-level: ~/.claude/CLAUDE.md -- personal instructions, lowest priority, not version-controlled
  4. Rules directory: .claude/rules/ files with optional glob patterns -- topic-specific, conditionally loaded

Key Rules

  • Project scope beats user scope: Same-named project skills/configs override user ones
  • No caching across sessions: CLAUDE.md is read fresh each session
  • New team members: If a guideline only exists in user-level files, new team members won't get it

Common Mistake

Team puts guidelines in each developer's ~/.claude/CLAUDE.md instead of the project's .claude/CLAUDE.md. New developers who join don't receive those guidelines. Solution: move shared guidelines to project scope.

The /memory Command

Use /memory to verify which memory files are loaded and diagnose inconsistent behavior across sessions. This helps identify when instructions are missing or incorrectly scoped.

Key Takeaways

  • Project CLAUDE.md is loaded for every conversation; user-level has lowest priority
  • Shared team guidelines must be in project scope, not user scope
  • CLAUDE.md is read fresh each session, no cross-session caching
  • Use /memory to verify which configuration files are loaded

Related Concepts

Modular CLAUDE.md with @import

@import lets each package selectively include relevant standards files

Path-Specific Rules (.claude/rules/)

Use .claude/rules/ with glob patterns for file-type-specific conventions

Test Yourself

1 / 3

Your CLAUDE.md has over 400 lines. You want Claude to always follow coding standards and testing conventions, but only apply PR review, deployment, and migration guidance when performing those tasks. What's the most effective restructuring?