GuidesHosting choices

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.

November 21, 2026The Everpod team
The short answer

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:

ScopePathFor
Managed policy
Linux and WSL: /etc/claude-code/CLAUDE.md; macOS: /Library/Application Support/ClaudeCode/CLAUDE.md; Windows: C:\Program Files\ClaudeCode\CLAUDE.mdInstructions for every user on the machine, deployed by IT
User
~/.claude/CLAUDE.mdYour preferences, in every project
Project
./CLAUDE.md or ./.claude/CLAUDE.mdThe team’s instructions, committed to the repository
Local
./CLAUDE.local.mdYour 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 ../shared
Copied

Beside 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 claude
Copied

Either 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.md
Copied

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.md
Copied

So 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/`.
Copied

The 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.md
Copied

The 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.

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.

Run Claude Code on an always-on developer pod.

A developer pod is a permanent cloud computer (VPS), set up and secured for you, with your pick of Claude Code, Codex, OpenCode, Pi, Hermes and OpenClaw installed. Run more agents at once than your laptop can hold, and keep them working when it’s closed. From $24 a month, built in about ten minutes.