CLAUDE.md
CLAUDE.md is Claude Code's Markdown instruction file, loaded at the start of every session to give Claude persistent project, user or organization guidance.
CLAUDE.md is the Markdown file Claude Code reads at the start of every session for persistent instructions: commands, conventions and project gotchas. It has managed, user, project and local scopes, concatenated root-down, supports @path imports and path-scoped .claude/rules, and is context Claude tries to follow, not enforced configuration.
CLAUDE.md is the Markdown instruction file that Claude Code loads at the start of every session so that project conventions, commands and constraints survive from one conversation to the next. Anthropic's documentation page for it is titled "How Claude remembers your project."
The file exists at four scopes, loaded from broadest to most specific: a managed policy file an organization deploys, ~/.claude/CLAUDE.md for everything you work on, ./CLAUDE.md or ./.claude/CLAUDE.md for the project (committed and shared), and ./CLAUDE.local.md for personal notes kept out of git. Claude Code reads the working directory and every directory above it at launch and concatenates what it finds, ordered from the filesystem root down, so the file closest to where you launched is read last. Files in subdirectories load on demand once Claude reads or edits something there.
Two mechanisms extend it. An @path/to/file line imports another file at launch, up to four hops deep; a path wrapped in backticks is left alone. And .claude/rules/*.md holds rule files that either load at launch or, with a paths: glob in their frontmatter, only when Claude touches a matching file. The docs warn that files over 200 lines may reduce adherence.
The limit worth remembering is that CLAUDE.md is advice, not enforcement. Its content arrives "as a user message after the system prompt," and Claude "treats them as context, not enforced configuration." Anything that must happen every time, such as blocking edits to a path, belongs in a hook. Since Claude Code v2.1.277 the tool also reads AGENTS.md natively when no CLAUDE.md exists above the working directory, which matters for repositories shared with Cursor or Codex; the instruction-file comparison covers that choice. CLAUDE.md best practices covers what to write in it, and memory and context covers how it loads alongside auto memory.
Frequently asked questions
- Where does Claude Code look for CLAUDE.md?
- In load order: a managed policy file deployed by your organization, ~/.claude/CLAUDE.md for all your projects, ./CLAUDE.md or ./.claude/CLAUDE.md for the project, and ./CLAUDE.local.md for personal notes. Files in the working directory and every directory above it load at launch and are concatenated; files in subdirectories load when Claude reads or edits a file there.
- What is the difference between CLAUDE.md and AGENTS.md?
- CLAUDE.md is Claude Code's native file, with @path imports and path-scoped .claude/rules. AGENTS.md is the cross-tool format read by Codex, Cursor, Copilot and others. Since v2.1.277, Claude Code reads AGENTS.md on its own when no CLAUDE.md exists in or above the working directory; otherwise it reads only the CLAUDE.md files.
- Does Claude Code always follow CLAUDE.md?
- No. Anthropic's docs say the content is delivered as a user message after the system prompt and that Claude treats it as context, not enforced configuration. Rules that must hold every time belong in a PreToolUse hook; CLAUDE.md is for conventions, commands and judgment calls.
Filed under
claude-md · claude-code · instructions · memory · configuration
Related
- AGENTS.md vs CLAUDE.md vs Cursor Rules: Which Instruction File Do You Need?AGENTS.md, CLAUDE.md, Cursor .mdc rules, GEMINI.md, Copilot instructions, Codex, Devin Desktop and Cline compared: who reads what, nesting, and migration.
- Cursor RulesCursor rules are persistent instructions for Cursor's AI agent: project rules as .cursor/rules/*.mdc files with frontmatter, plus User Rules and Team Rules.
- Managing Claude Code Memory & Context: CLAUDE.md, /compact, and Auto-MemoryHow Claude Code remembers — every CLAUDE.md scope and load order, path-scoped rules, the auto-memory system, and the context commands that keep sessions sharp.
- Claude Code Hooks: Automate Formatting, Tests, and GuardrailsHow Claude Code hooks work — the major hook events, the settings.json configuration shape, exit codes and JSON output, plus three hooks worth copying.
- AGENTS.mdAGENTS.md is a versioned instruction file that tells coding agents how to work in a repository — including commands, conventions, boundaries, and checks.
- Claude CodeAnthropic’s official agentic coding tool that runs in the terminal, IDE, and web.
- CLAUDE.md Best PracticesHow to write a CLAUDE.md that actually helps — what to include, what to leave out, and how to keep it current.