CLAUDE.md

How it works

Claude Code starts each new session with an empty context. CLAUDE.md is the set of instructions that goes into that context from the start. The official docs describe the file as context, not as enforced configuration. The more specific and short the instructions, the more consistently Claude follows them.

CLAUDE.md files in the current working directory and its parent directories are all read at startup and concatenated, ordered from the filesystem root down toward the working directory. A CLAUDE.md in a subdirectory is not loaded at startup. It loads when Claude reads or edits files in that directory.

• Project: ./CLAUDE.md or ./.claude/CLAUDE.md (shared with the team, checked into version control)
• Personal, all projects: ~/.claude/CLAUDE.md (applies to every project)
• Personal, one project: ./CLAUDE.local.md (the official docs say to add it to .gitignore)
• Organization policy: a managed CLAUDE.md placed in an OS-specific admin location

What to include and what to leave out

The docs use one test: add it if you keep explaining it again. Good moments to add a line are when Claude makes the same mistake twice, when a code review points out a codebase rule Claude missed, or when you are typing the same correction you used last session.

Good candidates are build and test commands, coding rules, project structure, and "always do X" rules. For multi-step procedures, or content that applies to only part of the codebase, the docs suggest moving it to a skill or to path-specific rules (.claude/rules/).

Write sentences you can verify. Instead of "keep the code clean," write "use 2-space indentation," "run npm test before committing," or "API handlers live in src/api/handlers/."

# Build and test
- Dev server: npm run dev
- Run npm test and npm run lint before committing

# Rules
- Use 2-space indentation
- API handlers live in src/api/handlers/

# Reference
See @README.md for project overview

Length and structure

The official recommendation is to aim for under 200 lines per file. Longer files use more context and get followed less closely. Group related instructions under headings and bullets, and prune contradictory instructions regularly. The docs note that when instructions conflict, Claude may pick one arbitrarily.

You can pull in other files with the @path syntax. Relative paths resolve relative to the file that contains the import, and imported files can import others up to four levels deep. Imported files still load into context along with the rest, so imports help organization but do not reduce context use. To mention a path in plain text without importing it, wrap it in backticks.

Block-level HTML comments (<!-- note -->) are stripped before the content is passed to Claude. You can leave notes for humans without spending tokens on them.

How it relates to nearby features

• /init: generates a CLAUDE.md draft. If one already exists, it suggests improvements instead of overwriting it.
• /memory: opens CLAUDE.md and auto memory for editing, and turns auto memory on or off.
• Auto memory: CLAUDE.md holds instructions you write. Auto memory holds notes Claude writes for itself from your corrections.
• /context: check the Memory files list to see what was loaded. If a file is not listed, Claude cannot see it.
• AGENTS.md: read by default only when there is no CLAUDE.md. To use both, import it from CLAUDE.md with @AGENTS.md.
• After /compact: the project-root CLAUDE.md is re-injected from disk. Instructions you only gave in conversation may be lost.

Real examples

Create CLAUDE.md in the project root with "# Build and test / Run npm test before committing", then run /context in a new session

Move the PR review and database migration procedures out of CLAUDE.md into skills, split the frontend rules into files under .claude/rules/, and keep only the shared rules in CLAUDE.md

Create CLAUDE.local.md in the project root with your personal address, and add CLAUDE.local.md to .gitignore

Common mistakes and when not to use it

• Trying to write everything down. The longer the file, the higher the context cost and the lower the compliance. Past roughly 200 lines, split it into skills or path-specific rules.
• Vague sentences like "keep it clean" or "do it well." Rewrite them as things you can check.
• Treating CLAUDE.md as enforcement. The official docs say it is context, not enforced configuration. If a behavior must be blocked, use a PreToolUse hook or permission settings.
• Thinking @imports solve the length problem. Imported files load into context too.
• Leaving old rules in place after the project changes direction. Claude may pick one of two conflicting instructions arbitrarily.

FAQ