CLAUDE.md

What is CLAUDE.md?

CLAUDE.md holds persistent instructions you write for Claude Code, loaded at the start of every session. The official docs say Claude treats it as context, not enforced configuration; to Block an action regardless of what Claude decides, use a PreToolUse hook. The more specific and concise the instructions, the more consistently Claude follows them.

Why does it exist?

Every Claude Code session starts with a fresh Context Window and remembers nothing of the last one. The official docs list two mechanisms for carrying knowledge across sessions: the CLAUDE.md you write, and auto memory that Claude writes itself from your corrections. CLAUDE.md is for rules and instructions, auto memory for learned habits and patterns.

How is it loaded?

Per the official docs: CLAUDE.md and CLAUDE.local.md in the working directory and every directory above it load at launch, concatenated rather than overriding each other, ordered from the filesystem root down to the working directory, so the closest instructions come last. Files in subdirectories load once Claude reads, writes or edits a file there. @path imports pull in other files, up to four hops deep. Scopes include managed policy, project, user and local (CLAUDE.local.md, which you should add to .gitignore). If only an AGENTS.md exists and no CLAUDE.md, Claude reads AGENTS.md; when both exist it reads only CLAUDE.md.

So what does this mean for me?

The docs advise keeping each CLAUDE.md under about 200 lines, since longer files use more context and reduce adherence; move rules relevant to only part of the codebase into path-scoped rules under .claude/rules/. If instructions contradict each other Claude may pick one arbitrarily, so prune periodically. A huge nested CLAUDE.md causes trouble: since v2.1.309 one over the limit loads only its start, to avoid repeated Compaction. In large monorepos claudeMdExcludes skips other teams' files, and a managed policy CLAUDE.md cannot be excluded.