CLAUDE.md File: What to Put in It and Where It Goes
September 30, 2026
A CLAUDE.md file is a plain markdown file that Claude Code reads at the start of every session. It's where you write down what you'd otherwise explain again every time: the build command, the test runner, the folder the API lives in, the thing Claude keeps getting wrong. Each session starts with an empty context window, so claude.md is how that knowledge carries over.
What to know, as of September 2026:
- It can live in four places. Organization, user, project, and a personal local file. Claude Code loads all of them together. None of them replaces another.
- Keep it short. Anthropic's docs suggest staying under 200 lines per file, and say longer files reduce how well Claude sticks to them.
- It's guidance, not enforcement. Claude reads it as context. If something must happen every single time, use a hook.
- Claude Code can now read AGENTS.md too, but by default only when there's no CLAUDE.md on the path.
Where Claude Code looks for CLAUDE.md
Anthropic's memory documentation lists four scopes. They load from broadest to most specific:
| Scope | Location | Use it for | Shared with |
|---|---|---|---|
| Managed policy | /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL, C:\Program Files\ClaudeCode\CLAUDE.md on Windows | Company standards, security and compliance reminders | Everyone on the machine |
| User | ~/.claude/CLAUDE.md | Your personal preferences across every project | Just you |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md | Build commands, conventions, architecture decisions | Your team, through git |
| Local | ./CLAUDE.local.md | Your sandbox URLs, your test data | Just you, and you add it to .gitignore |
These files don't override each other. Claude Code concatenates every file it finds into context. Launch Claude in foo/bar/ and it loads foo/CLAUDE.md, then foo/bar/CLAUDE.md, so the file nearest to where you started is read last. Inside each folder, CLAUDE.local.md goes after CLAUDE.md, which makes your personal notes the last thing Claude reads at that level.
CLAUDE.md files in subfolders below where you launched don't load at startup. They load when Claude reads a file in that subfolder, which suits a monorepo.
A managed policy CLAUDE.md can't be excluded by individual settings. Any other file that gets picked up by mistake, like another team's in a monorepo, can be skipped with the claudeMdExcludes setting.
What to put in a CLAUDE.md file
The docs give a simple test for when to add a line: Claude made the same mistake twice, a code review caught something Claude should have known, or you're typing the same correction you typed last session. If a new teammate would need it, Claude probably does too.
Anthropic's best practices guide splits it like this:
| Put it in | Leave it out |
|---|---|
| Bash commands Claude can't guess | Anything Claude can work out by reading the code |
| Code style rules that differ from the defaults | Standard language conventions |
| Which test runner to use, and how | Detailed API docs (link to them instead) |
| Branch naming and PR conventions | Information that changes often |
| Architecture decisions specific to your project | Long explanations or tutorials |
| Environment quirks, like required env vars | File-by-file descriptions of the codebase |
| Gotchas and non-obvious behavior | "Write clean code" and other self-evident advice |
The same guide gives the question to ask of every line: would removing it cause Claude to make mistakes? If not, cut it.
Write rules you can check. "Use 2-space indentation" works. "Format code properly" doesn't. "Run npm test before committing" works. "Test your changes" doesn't. When two instructions contradict each other, the docs say Claude may pick one arbitrarily, so an old rule you forgot about can quietly beat a new one.
A short example
Here's an illustrative CLAUDE.md for a hypothetical Next.js app. The project details are made up. The shape is the point:
# Commands
- Dev server: `pnpm dev`
- Run one test file: `pnpm vitest run path/to/file.test.ts`
- Typecheck before you say you're done: `pnpm typecheck`
# Code style
- TypeScript strict mode. No `any` in new code.
- Server actions live in `src/app/actions/`, one file per domain.
- Use the `logger` from `src/lib/log.ts`, never `console.log`.
# Workflow
- Branch names: `feat/short-name` or `fix/short-name`.
- Never edit files in `src/generated/`. Run `pnpm codegen` instead.
- IMPORTANT: database migrations need a human review. Stop and ask.
# More context
- API conventions: @docs/api-conventions.md
<!-- Maintainers: keep this under 200 lines. Move folder-specific rules to .claude/rules/ -->
The IMPORTANT goes on one line only. The best practices guide says emphasis helps a rule that keeps getting skipped, but if you emphasize many lines, none stands out. The HTML comment at the bottom is for humans. Claude Code strips block-level HTML comments before the file reaches Claude's context, so they cost no tokens.
Start with /init, then edit
You don't have to write the first draft yourself. Run /init in a session and Claude analyzes your codebase and writes a starting CLAUDE.md with the build commands, test instructions, and conventions it finds. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it.
Set CLAUDE_CODE_NEW_INIT=1 first and /init becomes interactive: it asks follow-up questions and shows you a proposal before writing anything.
/init also reads other tools' instruction files and folds the relevant parts in. By default that covers Cursor rules in .cursor/rules/ or .cursorrules and Copilot's .github/copilot-instructions.md. So if you already wrote Cursor rules, you're not starting over. The commands reference lists /init and the rest.
Treat the output as a draft. /init finds what's in the code. The valuable lines are the ones it can't find, like "the staging database is shared, never run destructive migrations against it."
Importing files with @path
A CLAUDE.md can pull in other files with @path/to/file. The imported file loads at launch alongside the CLAUDE.md that references it.
| Rule | What it means |
|---|---|
| Relative paths | Resolve from the file that contains the import, not from where you launched |
| Depth | Imports can import other files, up to four hops deep |
| Spaces in paths | Put a backslash before each space. A path in quotes isn't imported at all |
| Code spans | An @path inside backticks or a code block stays literal text |
| External files | The first time a project imports a file outside your working directory, Claude Code asks you to approve it |
Imports don't save context. This one catches people. The docs say splitting a long file into imports helps you organize it but doesn't reduce its context cost, because imported files also load at launch. If you want instructions that only load when relevant, you need a different tool.
That tool is .claude/rules/. Put one topic per markdown file in that folder. A rule with no frontmatter loads every session, like CLAUDE.md. A rule with a paths: field, such as src/api/**/*.ts, loads only when Claude reads a matching file. For multi-step procedures that only matter sometimes, the docs point to skills, which load on demand.
How big should CLAUDE.md be?
The documented numbers:
- Target under 200 lines per file. Longer files use more context and reduce adherence.
- Warnings. You see one at startup and in
/statuswhen a file goes over the recommended length. You also see one when several files that are each within the limit add up past a combined limit. - Hard ceiling. Claude Code loads a CLAUDE.md of up to 4 MiB in full and skips a larger one.
For a checked-in CLAUDE.md, /doctor proposes trims. It cuts what Claude can derive from the code, like directory layouts and dependency lists, and keeps pitfalls, reasoning, and conventions that differ from the defaults.
Size matters after long sessions too. The project-root CLAUDE.md is re-read from disk after a compaction. Nested ones and path-scoped rules only come back when Claude touches a matching file again. The Claude Code auto-compact guide covers what else survives.
When CLAUDE.md isn't enough
CLAUDE.md content is delivered as a user message after the system prompt. Claude tries to follow it, but the docs are plain that there's no guarantee of strict compliance.
| You need | Use |
|---|---|
| Standing context: commands, conventions, layout | CLAUDE.md |
| Rules for one part of the codebase | .claude/rules/ with paths: |
| A procedure Claude should run only sometimes | A skill |
| Something that must happen every time, like a lint after each edit | A hook |
| A hard block on a tool or command | permissions.deny in settings |
If Claude isn't following your file, run /context first and check the list under Memory files. If the file isn't there, Claude can't see it. For anything that must run at a fixed point, Claude Code hooks execute as shell commands whatever Claude decides.
Subagents get your instructions too. Per Anthropic's subagent docs, custom subagents load the same CLAUDE.md hierarchy as the main conversation. The built-in Explore and Plan agents skip it to stay fast, and a subagent definition can set omitClaudeMd to skip it as well. Our guide to Claude Code subagents covers how to set them up.
CLAUDE.md vs AGENTS.md
AGENTS.md describes itself as a simple, open format for guiding coding agents, and it's now stewarded by the Agentic AI Foundation under the Linux Foundation. Its site lists a range of coding agents and tools that read it. If your repo was set up for one of those first, you may already have one.
Claude Code reads AGENTS.md as of v2.1.277. Here's the default behavior, per Anthropic's memory docs:
| Your repository has | Claude reads |
|---|---|
| An AGENTS.md, and no CLAUDE.md or CLAUDE.local.md in your working directory or above | Your AGENTS.md |
| An AGENTS.md and a CLAUDE.md or CLAUDE.local.md on that path | Your CLAUDE.md files only |
A CLAUDE.md that imports @AGENTS.md | Both, through the import |
Notice the second row. Adding a CLAUDE.local.md for your own notes stops Claude from reading the team's AGENTS.md. Your ~/.claude/CLAUDE.md and the managed file don't count for that check, but the local file does.
To change the default, open /config and set Project instructions. claude-md-and-agents-md reads both, CLAUDE.md first in each folder. claude-md reads CLAUDE.md files only. Some sessions can't read AGENTS.md at all, such as older versions or ones where the built-in agents-md plugin is disabled. In those, the setting doesn't appear.
The simplest setup for mixed teams is to keep AGENTS.md as the shared file and add a small CLAUDE.md beside it:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
Claude reads the import first, then your Claude-specific lines. A symlink from CLAUDE.md to AGENTS.md also works, but the docs recommend the import if anyone on the team uses Windows. Git can check a symlink out as a one-line text file there.
If your repo has no agent context file at all, the AGENTS.md generator skill writes them per folder from your real scripts, and never overwrites one that exists.
Borrowing a setup that already works
A good CLAUDE.md is usually the product of weeks of corrections. Taku is built for the other way round. It's an AI-native desktop workspace where you mirror an AI setup, skill, or workflow someone already got working, run it, remix it for your own files, and keep it. It doesn't replace writing your own CLAUDE.md for your own codebase. It helps when you'd rather start from a proven setup than from a blank file. Taku is in Beta, and the Mac app is available now.
FAQ
What is a CLAUDE.md file?
A markdown file of standing instructions that Claude Code loads at the start of every session. It holds things like build commands, code style, and project conventions, so you don't have to repeat them.
Where should I put CLAUDE.md?
For team rules, at the project root as ./CLAUDE.md or ./.claude/CLAUDE.md, committed to git. Personal rules for every project go in ~/.claude/CLAUDE.md. Personal rules for one project go in CLAUDE.local.md, which you add to .gitignore.
Does Claude Code read AGENTS.md?
Yes, from v2.1.277, but by default only when there's no CLAUDE.md or CLAUDE.local.md in your working directory or above it. To use both, import @AGENTS.md from a CLAUDE.md or change Project instructions in /config.
Why is Claude ignoring my CLAUDE.md?
Run /context to check the file actually loaded. Then look for vague or conflicting instructions, and trim the file if it's long. If a rule must run every time, turn it into a hook.
Do @imports reduce context usage?
No. Imported files load at launch with the file that imports them. To load instructions only when relevant, use .claude/rules/ with paths: frontmatter, or a skill.