Claude Architect Lab

CLAUDE.md Configuration Hierarchy

Core

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

0%
claude-codeconfigurationclaude-mdhierarchy

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

Configuration Sources

  • Project CLAUDE.md: Root-level CLAUDE.md or .claude/CLAUDE.md -- loaded for every conversation
  • Directory CLAUDE.md: Subdirectory CLAUDE.md files -- additive context when working in those directories
  • User-level: ~/.claude/CLAUDE.md -- personal instructions, lowest priority, not version-controlled
  • 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 Yourself1 of 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?