CLAUDE.md Files

CLAUDE.md is Claude Code's primary configuration document — the first thing loaded at every session start. It tells Claude who you are, what the workspace contains, what conventions to follow, and where everything lives. Without it, Claude starts each session with no context. With a well-structured CLAUDE.md, you never repeat yourself across sessions.

The four-level hierarchy

CLAUDE.md files exist at four levels. Each level inherits from levels above it and adds its own specifics. More specific levels take precedence over broader ones.

# 1. Managed policy (organisation-wide — cannot be overridden)
/Library/Application Support/ClaudeCode/CLAUDE.md   ← macOS
%ProgramData%\AnthropicClaude\CLAUDE.md              ← Windows

# 2. User-level (applies to all your workspaces)
~/.claude/CLAUDE.md

# 3. Workspace-level (applies to this repository)
[workspace]/.claude/CLAUDE.md
[workspace]/CLAUDE.md

# 4. Project/subdirectory level
[workspace]/Claude Projects/P001-Name/CLAUDE.md
[workspace]/src/components/CLAUDE.md  ← loaded when Claude enters this directory

How CLAUDE.md files load

Loading is not all-at-once. Claude Code uses a lazy loading strategy:

• Workspace CLAUDE.md — loaded in full at every session start
• User-level CLAUDE.md — loaded in full at session start
• Rules files (.claude/rules/*.md) — loaded on-demand when Claude reads files matching the rule's glob pattern
• Subdirectory CLAUDE.md files — loaded on-demand when Claude enters or reads files in that directory
• Parent directory CLAUDE.md files — loaded when Claude operates in a subdirectory and walks up the tree

This means you can put component-specific instructions in src/components/CLAUDE.md without loading them into every session — they load only when Claude works in that directory.

What belongs in workspace CLAUDE.md

• Workspace identity — name, type (personal/client/internal), GitHub repo
• Primary role — one paragraph describing what Claude does in this workspace
• Terminology — terms with specific meanings that Claude might otherwise misinterpret
• Accessible folders — explicit list of paths Claude has access to
• File organisation — where different file types belong
• References — links to rules files, templates, profiles via @ imports

Imports via @path syntax

Long CLAUDE.md files become hard to maintain. Split content across files and import them with @path:

# CLAUDE.md

## Core Configuration
@.claude/rules/communication.md
@.claude/rules/blocked-commands.md
@~/.claude/personal-preferences.md

## Project Context
@Claude Projects/P001-Client/CLAUDE.md

Both relative and absolute paths work. Claude resolves @path references at load time and treats the imported content as part of the file. Import chains are followed up to 5 levels deep (A imports B which imports C — supported; chains beyond 5 are not followed).

Size discipline

Keep your master CLAUDE.md under 200 lines. This is not a hard limit — Claude will load larger files — but adherence degrades as size grows. Lines beyond 200 in the auto memory file (~/.claude/projects/[workspace]/memory/MEMORY.md) are truncated at session start and loaded on demand. Move detailed instructions to rules files and reference them with @ imports. A focused CLAUDE.md that links to well-organised rules is more effective than one long document.

Excluding CLAUDE.md files

If a workspace contains CLAUDE.md files you don't want Claude Code to load (e.g., documentation for a framework you're building, not instructions for Claude), use claudeMdExcludes in .claude/settings.json:

{
  "claudeMdExcludes": [
    "docs/**",
    "examples/**/CLAUDE.md"
  ]
}

The managed policy CLAUDE.md (set by an organisation administrator) cannot be excluded by users. All other levels are excludable.

Generate with /init

In an existing project, run /init — Claude analyses the directory structure and generates a draft CLAUDE.md reflecting what it finds. Edit the output to add your actual conventions; the generated version is a scaffold to start from, not a finished configuration. /init will not overwrite an existing CLAUDE.md — it presents the draft for you to review first.

Memory files vs CLAUDE.md

CLAUDE.md is for stable, intentional instructions — conventions you set deliberately. Memory files (~/.claude/projects/[workspace]/memory/MEMORY.md) are for facts Claude accumulates during use — preferences discovered, patterns confirmed, solutions to recurring problems. Both load at session start; both influence behaviour. The distinction: CLAUDE.md is what you write; memory is what Claude writes.