lockstep

CLAUDE.md

CLAUDE.md is the instruction file Claude Code reads at the start of every session: commands, conventions, and rules for a project, user, or organization.

CLAUDE.md is a markdown file of instructions that Claude Code reads at the start of every session. It is how you tell Claude Code what it would otherwise have to rediscover: build and test commands, conventions, where things live, and rules that always apply.

Where it lives

Per Anthropic's documentation, Claude Code reads CLAUDE.md from four places, broadest first:

ScopeLocationShared with
OrganizationA managed system path deployed by ITEveryone on the machine
User~/.claude/CLAUDE.mdOnly you, every project
Project./CLAUDE.md or ./.claude/CLAUDE.mdTeammates, through git
Local./CLAUDE.local.mdOnly you, this project

Files are concatenated, not merged, so conflicting instructions can both load. An organization can also deploy a managed CLAUDE.md; see Claude Code managed settings. CLAUDE.md files in subdirectories load only when Claude works on files there.

What it is not

CLAUDE.md is context, not enforcement. Claude reads it and tries to follow it, but there is no guarantee. Rules that must never be broken belong in hooks or permission settings. For the common reasons instructions get ignored, see why Claude Code ignores your CLAUDE.md.

It also isn't the place for decisions that change often. A file has no owner per line and no record of what replaced what, which is how it fills with outdated rules. For the full picture of Claude Code's memory, see how Claude Code memory works, and for the vendor-neutral alternative, see AGENTS.md vs CLAUDE.md. For a template and examples, see CLAUDE.md examples.

What is CLAUDE.md?
A markdown file of instructions that Claude Code loads into context at the start of every session. It holds build commands, conventions, project layout, and rules, and can live at the organization, user, project, or local level.
Where does CLAUDE.md go?
A project CLAUDE.md goes in the repository root as ./CLAUDE.md or ./.claude/CLAUDE.md and is shared through git. Your personal one is ~/.claude/CLAUDE.md, and CLAUDE.local.md holds private notes for one project.
How long should CLAUDE.md be?
Anthropic recommends under 200 lines per file. Longer files use more context and are followed less reliably, and a file over 4 MiB is skipped entirely.

Related