Claude Code Configuration & Workflows/Configuration
★ OverviewIntermediate12 min

CLAUDE.md Hierarchy & Scoping

How CLAUDE.md files are resolved across user, project, and directory scopes. Inheritance rules, @import syntax, .claude/rules/ organization, and strategies for team-wide consistency.

Quick Reference

  • →Three hierarchy levels: user (~/.claude/CLAUDE.md), project (root CLAUDE.md or .claude/CLAUDE.md), directory (subdirectory CLAUDE.md)
  • →User-level config is NOT version-controlled -- it lives in your home directory and is personal
  • →Project-level config IS committed to git -- the whole team shares it
  • →Directory-level CLAUDE.md files apply only when Claude edits files in that subdirectory
  • →All levels are additive -- they merge together, they do NOT override each other
  • →@import syntax lets you split large CLAUDE.md files into modular pieces
  • →.claude/rules/ directory holds topic-specific rule files with optional glob-based path scoping
  • →Use /memory command to verify which CLAUDE.md files are currently loaded
  • →CLAUDE.md is read on every conversation turn -- keep it concise to avoid wasting context tokens
  • →Enterprise projects often use @import to split standards into testing, security, API, and style modules

What is CLAUDE.md?

Definition

CLAUDE.md is a special markdown file that provides persistent instructions to Claude Code. It is read on every conversation turn and acts as your project's memory -- coding standards, architectural decisions, and workflow preferences that Claude should always follow.

Think of CLAUDE.md as the .editorconfig or .eslintrc of the AI era -- but instead of configuring a linter, you are configuring an AI coding assistant. Without CLAUDE.md, Claude Code starts every session with zero project knowledge. It will make reasonable guesses, but those guesses may conflict with your team's conventions. CLAUDE.md solves this by giving Claude a persistent set of instructions that survive across sessions and are shared across the team via version control.

Claude Code supports multiple CLAUDE.md files at different levels of your file system. These files form a hierarchy that lets you set broad rules at the user or project level and narrow, specific rules at the directory level. Understanding this hierarchy is critical for the exam -- it appears in multiple scenarios and is the foundation of how Claude Code configuration works.