CLAUDE.md: where Claude Code reads it from and what to put in it
What CLAUDE.md is, every place Claude Code loads one from and in what order, /init and /memory, @imports, how it sits with AGENTS.md, and auto memory.
CLAUDE.md is a Markdown file of standing instructions that Claude Code loads into every session: your build and test commands, conventions and “always do X” rules. It reads one from four places, broadest first: a managed file your organisation can deploy (/etc/claude-code/CLAUDE.md on Linux), your own ~/.claude/CLAUDE.md, the project’s ./CLAUDE.md or ./.claude/CLAUDE.md, and a personal ./CLAUDE.local.md. Every file found is added to context, none replaces another, and a CLAUDE.md in a subdirectory loads only once Claude touches a file there. Run /init to generate one and /memory to open and edit them. Anthropic’s advice is to keep each under 200 lines.
Every place Claude Code reads a CLAUDE.md
Anthropic’s memory documentation lists the locations in load order, from broadest scope to most specific, as it stood in November 2026:
| Scope | Path | For |
|---|---|---|
Managed policy | Linux and WSL: /etc/claude-code/CLAUDE.md; macOS: /Library/Application Support/ClaudeCode/CLAUDE.md; Windows: C:\Program Files\ClaudeCode\CLAUDE.md | Instructions for every user on the machine, deployed by IT |
User | ~/.claude/CLAUDE.md | Your preferences, in every project |
Project | ./CLAUDE.md or ./.claude/CLAUDE.md | The team’s instructions, committed to the repository |
Local | ./CLAUDE.local.md | Your own notes for this project, kept out of git |
At launch Claude Code walks from your working directory up to the filesystem root and loads every CLAUDE.md and CLAUDE.local.md it finds. The docs say they are “concatenated into context rather than overriding each other”: the root-most file comes first, and the one in the directory you started in comes last. Within one directory, CLAUDE.local.md goes after CLAUDE.md. Nothing wins on conflict; where two files contradict each other, “Claude may pick one arbitrarily.”
A CLAUDE.md in a subdirectory below where you started is not loaded at launch. It loads the first time Claude reads, writes or edits a file in that subdirectory, and it is cut off at 40,000 characters on a 200K-token context window (since v2.1.309), with a note telling Claude to read the rest. A file that loads at launch is read whole up to 4 MiB; one over 4 MiB is skipped entirely. Directories added with --add-dir contribute no CLAUDE.md unless you start with this variable set:
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../sharedCopiedBeside the CLAUDE.md files, Markdown files in .claude/rules/ (and your own ~/.claude/rules/) are instructions too. A rule with no paths frontmatter loads at launch like .claude/CLAUDE.md; one with paths loads only when Claude works on a matching file.
On a server
The user file is ~/.claude/CLAUDE.md in the home directory of the account that runs claude, so on a server it follows the login: run it as deploy and it reads /home/deploy/.claude/CLAUDE.md; run it as root and it reads root’s. That follows from the path; a file you wrote on your laptop is not there until you copy it. If CLAUDE_CONFIG_DIR is set, the .claude directory docs say every ~/.claude path moves under that directory instead, this file included.
On a machine several people or several agent accounts share, /etc/claude-code/CLAUDE.md is the file every account gets, since the managed file applies to all users on the machine. It loads before user and project files, and claudeMdExcludes cannot switch it off. Writing it needs root. Setting up the rest of the machine is in running Claude Code on a VPS.
Creating one with /init
Type /init in a session at the project root. Per the docs, Claude analyses the codebase and writes a CLAUDE.md with the build commands, test instructions and conventions it finds; if a CLAUDE.md already exists, it suggests improvements instead of overwriting it. It also folds in Cursor rules (.cursor/rules/ or .cursorrules) and .github/copilot-instructions.md.
For a longer, interactive version, set CLAUDE_CODE_NEW_INIT=1 before running it. It then asks which of CLAUDE.md files, skills and hooks to set up, asks follow-up questions, and shows a proposal to review before it writes anything; it also reads an existing AGENTS.md and can create your gitignored CLAUDE.local.md.
CLAUDE_CODE_NEW_INIT=1 claudeCopiedEither way, the generated file is a start: Anthropic suggests refining it with what Claude would not discover on its own.
Editing and checking with /memory
/memory lists your CLAUDE.md, CLAUDE.local.md and other memory files across user and project scopes, including entries for files that do not exist yet; picking one opens it in your editor, creating it first if needed. A terminal editor such as Vim takes over the terminal until you exit it, which is what you get over SSH. The same screen toggles auto memory and opens its folder.
To see what actually loaded, run /context all and read the list under Memory files. A file missing there is not in front of Claude. A subdirectory CLAUDE.md never appears in that list, because it loads on demand; when it does load, a Loaded line with its path appears in the terminal.
To add a rule to the file from the conversation, say so: “add this to CLAUDE.md”. Asking Claude to “remember” something saves it to auto memory instead (below).
Importing other files with @path
A line such as @docs/git-instructions.md anywhere in a CLAUDE.md expands that file into context at launch, alongside the CLAUDE.md:
See @README for project overview and @package.json for npm scripts.
# Additional Instructions
- git workflow @docs/git-instructions.mdCopied- Relative paths resolve from the file holding the import, not from your working directory. Absolute paths and
@~/...work too. - Imports can import other files, at most four hops deep.
- For a space in a path, put a backslash before it:
@Design\ Docs/api.md. A path in quotes is not imported at all. - An
@pathinside backticks or a fenced code block stays literal text. - An import in a project file that points outside the working directory, such as one in your home directory, triggers an approval dialog the first time; decline it and those imports stay off for the project. Imports in your own
~/.claude/CLAUDE.mdload without asking. - Imports organise a long file but do not shrink it: the imported text counts against context like the rest.
CLAUDE.md and AGENTS.md
Since v2.1.277 Claude Code reads AGENTS.md directly, but by default only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it. Your ~/.claude/CLAUDE.md, the managed file and rules files do not count, and load alongside it. When it does read AGENTS.md, an interactive session shows a line such as:
no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.mdCopiedSo adding a CLAUDE.md, or even a personal CLAUDE.local.md, to a repository that relies on AGENTS.md stops Claude reading the AGENTS.md. There are two ways to keep both. One is an import at the top of the CLAUDE.md, with anything Claude-specific after it, which Claude reads in that order:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.CopiedThe other is the Project instructions setting in /config: claude-md-and-agents-md reads both, each directory’s CLAUDE.md first; the default is claude-md-or-agents-md. A CLAUDE.md that only says in words “read AGENTS.md” is not the same thing: in the docs’ words, “Claude sees AGENTS.md only if it decides to open the file.” AGENTS.override.md and AGENTS.local.md are never read. How Codex, Cursor and the others read the same file is in what AGENTS.md is and which agents read it.
Auto memory: the notes Claude writes itself
CLAUDE.md is what you write. Auto memory is what Claude writes: your preferences, corrections you gave it, project decisions it cannot get from the code. It is on by default in local sessions and lives per repository, shared across worktrees, at:
~/.claude/projects/<project>/memory/MEMORY.mdCopiedThe first 200 lines or 25KB of MEMORY.md, whichever comes first, load at session start; the topic files it indexes are read when needed. It is machine-local, so notes Claude saved on your laptop are not on your server. Turn it off with the toggle in /memory, with "autoMemoryEnabled": false in a project’s settings, or with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. The automatic cleanup of old transcripts leaves these files alone; deleting a project’s history by hand is covered in deleting Claude Code sessions and history.
What a good CLAUDE.md holds
Anthropic’s guidance, in short: “Keep it to facts Claude should hold in every session: build commands, conventions, project layout, ‘always do X’ rules.” Add to it when Claude makes the same mistake twice, or when you type the same correction you typed last session.
- Short. Under 200 lines per file; longer files “consume more context and reduce adherence.” Claude Code warns at startup and in
/statuswhen a file is over the recommended length. - Concrete enough to check. “Use 2-space indentation” rather than “Format code properly”; “Run
npm testbefore committing” rather than “Test your changes”. - Grouped under headings, and free of contradictions with the other files that load.
- Not procedures. A multi-step workflow belongs in a skill, which loads only when used, and instructions for one part of the code in a path-scoped rule.
- Notes for humans in HTML comments. Block-level
<!-- ... -->comments are stripped before the file reaches Claude.
CLAUDE.md is guidance, not enforcement: it reaches the model as a user message after the system prompt, and the docs say there is no guarantee of strict compliance. Something that must happen every time, before each commit or after each edit, is a hook, and a command that must never run is a permissions.deny rule in settings. To have Claude look for stale or conflicting instructions across your files, run /doctor prompt-audit (v2.1.283 and later); it proposes edits and changes nothing until you say so.