The Complete CLAUDE.md Guide: Project Memory for Claude Code

CLAUDE.md is a markdown instruction file that Claude Code reads automatically at the start of every session. Write down the things you would otherwise re-explain every time — build commands, coding rules, project layout — and Claude starts each conversation with that context. This guide, based on Anthropic's official docs, covers where to put CLAUDE.md, how to write it, and how to manage it.

What is CLAUDE.md

Each Claude Code session starts with a fresh context window. CLAUDE.md fills that blank slate with "what always applies in this project." You write it in plain markdown, and Claude reads it at the start of every session. The official docs describe CLAUDE.md as the place to write down what you would otherwise re-explain.

One thing to be clear about: CLAUDE.md is delivered as context, not as enforced configuration. Claude reads it and tries to follow it, but compliance is not 100% guaranteed. For rules that must block or run no matter what, use a hook or managed settings instead.

Two memories: CLAUDE.md and auto memory

Claude Code's memory has two parts, both loaded at the start of every session.

• CLAUDE.md — instructions and rules you write: coding standards, workflows, project architecture.
• Auto memory — learnings and patterns Claude records as it works (build commands, debugging insights, preferences). On by default; requires Claude Code v2.1.59 or later.

In short: rules you want to control go in CLAUDE.md; experience Claude accumulates on its own goes in auto memory.

Where to put it: four locations

CLAUDE.md can live in several locations by scope, loaded from broadest to most specific (see the figure). All files are concatenated into context rather than overriding each other.

• Managed policy — whole org. macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux/WSL /etc/claude-code/CLAUDE.md, Windows C:\Program Files\ClaudeCode\CLAUDE.md. Cannot be excluded by individual settings.
• User — ~/.claude/CLAUDE.md. Personal preferences across all your projects.
• Project — ./CLAUDE.md or ./.claude/CLAUDE.md. Shared with your team via version control.
• Local — ./CLAUDE.local.md. Personal project-specific settings; add it to .gitignore.

Claude Code walks up the directory tree from your working directory, collecting each folder's CLAUDE.md, and concatenates from the root down toward your working directory. CLAUDE.md files in subdirectories load on demand when Claude reads files there.

The fastest start: /init

Starting from scratch? Run /init in Claude Code. Claude analyzes your codebase and drafts a CLAUDE.md with build commands, test instructions, and project conventions it discovers. If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it.

How to write it well

CLAUDE.md is loaded into context in full regardless of length (unlike auto memory), so to save tokens and improve adherence:

• Size: target under 200 lines per file. Longer files consume more context and reduce adherence.
• Specificity: write instructions concrete enough to verify. "2-space indentation" beats "format code nicely."
• Structure: group related instructions with markdown headers and bullets.
• Consistency: if two rules contradict, Claude may pick one arbitrarily — review periodically.

Import other files: @import

CLAUDE.md can pull in other files with the @path syntax. Relative and absolute paths both work, and imported files can recursively import others up to a maximum depth of four hops.

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

To share personal instructions across multiple git worktrees, importing a file from your home directory (@~/.claude/my-project-instructions.md) is convenient.

Split rules with .claude/rules/

For larger projects, organize instructions into topic files under .claude/rules/. Add a paths: frontmatter glob to a file and that rule loads only when Claude works with matching files, saving context.

If your repo uses AGENTS.md

Claude Code reads CLAUDE.md, not AGENTS.md. If you already have AGENTS.md, import it from CLAUDE.md with @AGENTS.md so both tools share the same instructions — and add Claude-specific notes below it if needed.

A quick look at auto memory

Auto memory is notes Claude records as it works, stored per repository as markdown under ~/.claude/projects/<project>/memory/. Only the start of the index file MEMORY.md (first 200 lines or 25KB, whichever comes first) is loaded each session; detailed notes are read on demand. Use /memory to browse loaded files and toggle auto memory.

When Claude doesn't follow CLAUDE.md

CLAUDE.md is delivered as a user message after the system prompt, so it is not strictly enforced. If it is being ignored: (1) run /memory to confirm the file is actually loaded, (2) make instructions more specific, and (3) remove conflicts between files. For something that must run at a fixed point (e.g., before every commit), write it as a hook instead.

Related reading · source

For ready-to-use examples, see the CLAUDE.md templates. The facts in this article follow Anthropic's official Claude Code docs — code.claude.com/docs/en/memory. Specific behavior may change by version.