CLAUDE.md: The Claude Code Instruction File Explained

A new wave of Claude Code users lands every week. Many start a session, type their first prompt, and within an hour notice that Claude is re-discovering the same project conventions, asking how to run the tests, or making the same correction the team has flagged twice already. The answer is one file: CLAUDE.md.

This article explains what CLAUDE.md is, where it lives in the Claude Code memory hierarchy, how it loads, and what to put in it (and what to keep out). It is written for people new to Claude Code who want a clean reference, and for developers who have used Claude Code for months and want to understand the memory layer they have been working alongside.

The technical reality worth opening with: Claude Code's system prompt already uses about 50 of the 150 to 200 instructions a frontier thinking model can reliably follow [4]. Your CLAUDE.md competes with the remainder. Claude Code also attaches a <system-reminder> to your file telling Claude that the content may or may not be relevant, and to ignore it if it judges the context unrelated to the task [4]. Most CLAUDE.md files end up partly ignored.

Here is how the file behaves at runtime, and how to write one Claude Code will read.

Why I dug into this

I am an engineer by trade. When I started using Claude Code, my first instinct was to find the configuration surface, reach in, and tune it until the agent's behaviour became as deterministic as I could make it. That reflex (edit the config, change the behaviour, observe the difference) is how engineers learn any system.

The first problem I wanted to solve was simple: give the agent project context the moment a session launched, by pointing it at a specific directory path so it could read the repo it was working in and the project it should focus on. That problem turned out to have a one-line solution (@AGENTS.md at the top of CLAUDE.md). The longer answer (which file does what, when each one loads, and how they stack) is what this article covers.

What CLAUDE.md is

CLAUDE.md is a plain Markdown file Claude Code reads at the start of every session [1]. The default location is the project root, either ./CLAUDE.md or ./.claude/CLAUDE.md [1]. The Claude Code docs describe it as one of two mechanisms that carry knowledge across sessions, alongside auto memory:

Source: Anthropic, How Claude remembers your project [1].

The two mechanisms work together. Claude Code treats both as context, with the level of adherence shaped by how specific and concise the instructions are [1].

A mental model in plain terms

Think of CLAUDE.md as the project's onboarding document for Claude. A new human engineer joining the team gets a README, a Slack channel, a code walkthrough, and a list of build commands. Claude joins every session needing the same context delivered upfront. CLAUDE.md is the single document that hands Claude that context, compressed enough to fit in the few hundred lines that load every session.

From first principles

At first principles, an LLM session is stateless. Every new session starts fresh. Claude needs the project facts, codebase conventions, team preferences, and standing corrections delivered upfront. To make the same model behave consistently across sessions, two things have to happen between the new session opening and the first useful prompt:

• The project's facts (build commands, conventions, constraints) have to land in the context window.
• The agent has to apply those facts as standing rules with the same weight on turn 1 and turn 100.

CLAUDE.md is what handles the first step. The placement of the file inside the system prompt (Claude reads it on every session start) is what handles the second.

The four scoping levels

A CLAUDE.md file can live at four scopes, each with a different purpose and visibility [1].

Managed policy is the org control surface: company coding standards, security policies, compliance requirements [1]. Project is the team-shared standard. User is your personal preferences (tooling shortcuts, your own commit conventions). Local is per-project per-developer overrides that should stay out of git. The OS-specific managed-policy paths are: /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux/WSL, and C:\Program Files\ClaudeCode\CLAUDE.md on Windows [1].

How CLAUDE.md files load

Claude Code walks up the directory tree from the working directory, gathering every CLAUDE.md and CLAUDE.local.md along the way [1]. All discovered files are concatenated into context, with content ordered from the filesystem root down to the working directory. Within each directory, CLAUDE.local.md is appended after CLAUDE.md, so personal notes are the last thing Claude reads at that level [1].

This loading model has four practical consequences:

• Subdirectory files load on demand. CLAUDE.md files in subdirectories under the cwd load when Claude reads files in those subdirectories, in addition to the launch-time chain [1].
• HTML comments are stripped before injection. <!-- maintainer notes --> blocks survive in the file but cost zero context tokens [1]. Useful for human-only context.
• Monorepo exclusions. The claudeMdExcludes setting tells Claude Code to skip other teams' CLAUDE.md files in monorepo cases where their content is irrelevant to your work [1].
• Additional directories. The --add-dir flag plus CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 environment variable loads CLAUDE.md from directories outside the main working tree [1].

The "more-specific takes precedence" framing is shorthand: every level concatenates, and the most local file appears last in the combined prompt. Because LLMs bias towards instructions at the prompt periphery [4], that recency effect is what gives nested files their precedence.

The @ import syntax

CLAUDE.md files can pull in additional files using @path/to/import syntax [1]. The imported content expands and loads alongside the file that references it, at session launch.

Three details matter:

• Both relative and absolute paths work. Relative paths resolve to the file containing the import, the working directory [1].
• Recursive imports up to 5 hops. Imported files can themselves import other files, with a hard depth limit of five [1].
• External imports prompt for approval. The first time Claude Code encounters an import that points outside the project, an approval dialog appears. Decline once and the imports stay disabled with no further prompts [1].

The canonical interop pattern with AGENTS.md is one line at the top of CLAUDE.md, followed by Claude-specific instructions [1]. For the deeper explainer on what AGENTS.md is and what 25+ agents do with it, see our AGENTS.md companion piece.

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

This is the Anthropic-recommended pattern for repos that already use AGENTS.md for other coding agents. The earlier ln -s AGENTS.md CLAUDE.md symlink approach (Matt Pocock at AI Hero [7]) still works and is widely cited. The @AGENTS.md import is the newer official approach: it preserves the ability to add Claude-specific instructions below the import, which the symlink does at the cost of treating the two files as identical.

Anatomy of a good CLAUDE.md

The official guidance and the most-cited community analysis converge on the same point: keep the file small.

Anthropic's docs target under 200 lines per file [1]. HumanLayer reports their own root CLAUDE.md is under 60 lines [4]. The arithmetic explains why: Claude Code's system prompt already uses about 50 individual instructions, and a frontier thinking model follows roughly 150 to 200 instructions reliably (per arxiv 2507.11538, cited in HumanLayer's analysis) [4]. Every byte in CLAUDE.md competes with the remaining budget.

What goes in

• 1-2 lines of project context (what this project is, why it exists).
• Essential build, test, and dev commands the agent will run every session.
• Naming and architectural conventions Claude must learn from explicit instructions.
• Pointers to other documents (e.g., "For billing logic, read docs/billing-architecture.md").
• Things you have corrected the same way more than once.

What goes out

• Code style guidelines. Use a linter or formatter. Claude is slower and more expensive than a deterministic tool for that job [4].
• One-off implementation hotfixes. These belong in skills or in path-scoped rules under .claude/rules/, where they load only when relevant [1].
• File-type-specific guidance. Path-scoped rules in .claude/rules/ are designed for this and load only when Claude reads matching files [1].
• Cross-platform repo rules. These belong in AGENTS.md, which can then be imported via @AGENTS.md. See our AGENTS.md explainer for the cross-platform contract.

Three example CodeBlocks

Minimal CLAUDE.md:

# CLAUDE.md

This is a Next.js 16 marketing site. Sanity is the CMS. Vercel hosts.

## Commands
- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`

## Conventions
- TypeScript strict mode
- Page routes go in `app/`; shared UI in `components/`

Project CLAUDE.md with @AGENTS.md import:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.
When running `/init`, prefer the multi-phase flow (`CLAUDE_CODE_NEW_INIT=1`).

Monorepo CLAUDE.md with nested files and exclusions:

# CLAUDE.md (repo root)

This is the platform monorepo. Each package has its own `CLAUDE.md`.
Claude Code loads the closest file when working in a subdirectory.

@AGENTS.md

<!-- claudeMdExcludes is set in .claude/settings.json to skip
     packages/legacy-billing where the team uses different conventions. -->

How to write one

For the visual map of how CLAUDE.md sits alongside SKILL.md, AGENTS.md, and the rest of the agent-config family, see the Agent Skills Landscape infographic.

Common mistakes

• Auto-generating the file with /init and shipping it as written. HumanLayer's specific recommendation: hand-write CLAUDE.md [4]. Generated files include broadly applicable scaffolding that bloats the instruction budget.
• Stuffing the file with code style guidelines. Use linters and formatters. Claude is the wrong tool for that job [4].
• Cross-platform rules in CLAUDE.md. Other agents (Codex, Cursor, Copilot) read AGENTS.md; rules in CLAUDE.md stay invisible to them. Cross-platform rules belong in AGENTS.md and get imported via @AGENTS.md.
• Claude-specific flags in AGENTS.md. Other agents follow them and break.
• Secrets in CLAUDE.md. The file ships in git by default. Use CLAUDE.local.md (gitignored) for personal overrides.
• One-shot CLAUDE.md written once and forgotten. Revisit the file when you find yourself typing the same correction into chat for the second time [1].

How CLAUDE.md fits with the agent-config stack

CLAUDE.md is one of several mechanisms Claude Code reads. The others serve different purposes:

• AGENTS.md is the cross-platform contract read by 25+ agents (Codex, Cursor, Copilot, Aider, opencode, and others). CLAUDE.md imports it via @AGENTS.md for the Claude Code session [1]. Read the AGENTS.md explainer for the deeper treatment.

• SKILL.md files describe portable agent skills that load only when invoked or judged relevant. They sit at the skill layer and pair with CLAUDE.md at the instruction layer. See our Skills Hub for the SKILL.md directory.
• .claude/rules/ holds path-scoped rules that load only when Claude reads matching files. Better than CLAUDE.md for file-type-specific guidance (testing rules, API rules, framework conventions) because the rules stay out of context until they apply [1].
• Auto memory lets Claude write its own notes about your corrections and preferences. Per working tree, first 200 lines or 25KB loaded each session. Complementary to CLAUDE.md: you write the rules, Claude writes the learnings [1].

The stack:

• AGENTS.md for cross-platform repo rules
• CLAUDE.md for the Claude-specific overlay (with @AGENTS.md import at the top)
• .claude/rules/ for path-scoped instructions
• Skills for opt-in capabilities
• Auto memory for Claude's own learnings

Each file earns its place by serving one of those purposes. None of them serves all of them.

You have probably already touched one

If you have used Claude Code, you have already worked alongside a CLAUDE.md. Maybe you opened it. Maybe /init generated one for you on day one and you scrolled past it. Maybe a teammate set it up and you have been working over the top of it ever since. Maybe you have run /memory once and seen the chain that loads at session start. The file is already in your workflow; the question is whether you are using it deliberately.

The high-leverage thing you can do with CLAUDE.md is treat it as a live experiment. Edit it. Add a constraint. Run a session. See whether Claude's behaviour shifts the way you expected. Add another constraint. Re-run. The file is plain Markdown checked into git, so every change is reversible in one revert. The way to develop a feel for what Claude treats as a standing rule and what gets dropped under the system-reminder is to put rules in the file and watch the difference.

Operators who get good at CLAUDE.md fast are the ones who tamper with it. They add a rule, see what changes, prune the noise, sharpen the rules that matter, and end up with a file under sixty lines that consistently shapes the agent's behaviour.

Start small. Add the build and test commands. Add the constraints you have already typed into chat twice. Use @AGENTS.md to import the cross-platform rules from one source of truth. Run the session. Observe. Iterate. The file rewards experimentation more than it rewards comprehensive first drafts.

Edit it. Break it. Re-run. That is how you learn what the file does.