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:
| Scope | Location | Shared with |
|---|---|---|
| Organization | A managed system path deployed by IT | Everyone on the machine |
| User | ~/.claude/CLAUDE.md | Only you, every project |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md | Teammates, through git |
| Local | ./CLAUDE.local.md | Only 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