F4.3 F4

Three Levels of CLAUDE.md: User, Project, Directory

Claude Code’s configuration system has three levels, and they exist for a practical reason: teams need shared standards, individuals need personal preferences, and specific code areas sometimes need their own rules.

The three levels

  1. User-level (~/.claude/CLAUDE.md) — personal preferences. Your coding style, your tool habits, your workflow quirks. Lives in your home directory. Not committed to version control. Only affects you.

  2. Project-level (CLAUDE.md at project root) — team standards. Coding conventions, naming rules, architectural patterns. Committed to version control. Shared with every team member through git.

  3. Directory-level (CLAUDE.md in subdirectories) — local rules for specific code areas. The api/ directory might have different conventions than the frontend/ directory. These load only when Claude works on files in that subdirectory.

All three levels load simultaneously and combine. They don’t override each other with strict priority — they layer together. Team standards from the project level plus your personal preferences from the user level both apply at the same time.

Beyond CLAUDE.md

The configuration system includes more than just CLAUDE.md:

  • .claude/rules/*.md — modular rule files with optional YAML frontmatter containing glob patterns. Rules load conditionally based on which files Claude is working on.
  • .claude/commands/*.md — custom slash commands. Team-shared workflows defined as markdown files.
  • .claude/skills/*/SKILL.md — skills with frontmatter configuration including context isolation (context: fork) and tool restrictions.

All of these support both user-level (~/.claude/) and project-level (.claude/ in project root) placement. The feature set is equivalent at both levels — user-level isn’t limited to basic CLAUDE.md only.

MCP server configuration

MCP servers have their own dedicated config file: .mcp.json at the project root for team-shared server configuration. This is separate from CLAUDE.md — instructions live in CLAUDE.md, server configuration lives in .mcp.json. Commit .mcp.json to version control so everyone has the same MCP servers. Secrets use ${ENV_VAR} expansion syntax.

The team setup pattern

The standard organizational approach: put team coding standards in project-level CLAUDE.md (everyone gets them via git). Put personal preferences in user-level ~/.claude/CLAUDE.md (only you see them). When team standards update, everyone gets the changes on their next pull. No manual copying, no drift, no comment-out hacks.

One-liner: User-level for personal preferences, project-level for shared team standards, directory-level for local rules — all load simultaneously and combine, with MCP config in a separate .mcp.json.