The CLAUDE.md file: where it goes, what to put in it, and what to keep out
CLAUDE.md is the file Claude Code reads at the start of every session. Put the right things in it and Claude follows your project's rules; put everything in it and it follows none of them well.
Updated 13 November 2026. Every behaviour described here comes from Anthropic's Claude Code documentation, read that day.
CLAUDE.md is a Markdown file of instructions that Claude Code loads into context at the start of every session. Put one at the root of your repository for the project's rules, and one in ~/.claude/CLAUDE.md for your personal preferences across all projects. Keep each under about 200 lines, write instructions concrete enough to check, and move anything that only matters for part of the code into .claude/rules/. Run /init to generate a first version.
Where Claude Code looks for CLAUDE.md
- Project: ./CLAUDE.md or ./.claude/CLAUDE.md. Shared with your team through version control: architecture, commands, conventions.
- User: ~/.claude/CLAUDE.md. Your personal preferences, applied to every project on your machine.
- Local: ./CLAUDE.local.md. Personal notes for this project only; add it to .gitignore.
- Managed policy: /etc/claude-code/CLAUDE.md on Linux, /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, C:\Program Files\ClaudeCode\CLAUDE.md on Windows. Set by an organisation for everyone.
Files are added together, not overridden. Claude Code loads the CLAUDE.md and CLAUDE.local.md of your working directory and of every directory above it at launch, ordered from the root down. CLAUDE.md files in subdirectories load later, when Claude reads or edits a file there. Source: Claude Code documentation.
Create it with /init
In a session, /init analyses your codebase and writes a starting CLAUDE.md with the build commands, test instructions and conventions it finds. If the file already exists, it suggests improvements instead. Treat the result as a draft: remove what is obvious from the code and add what Claude cannot guess.
What to put in it
- Commands Claude cannot guess: how to build, test, lint and run one test.
- Conventions that differ from the defaults: “2-space indentation”, “API handlers live in src/api/handlers/”.
- Things never to do: “never edit generated files in dist/”, “don't add dependencies without asking”.
- Where things are: the few folders that matter and what lives in them.
- How you want to work: commit message format, when to ask before acting.
Anthropic's advice is to write instructions concrete enough to verify: “Run npm test before committing” rather than “Test your changes”. Group them under headings and bullets. If two instructions contradict each other, Claude may pick either.
# Project: invoicing API
## Commands
- Install: `pnpm install`
- Test all: `pnpm test` · one file: `pnpm test src/invoices/total.test.ts`
- Lint before committing: `pnpm lint`
## Conventions
- TypeScript strict, 2-space indentation, named exports only
- API handlers in `src/api/handlers/`, one file per route
- Amounts are integers in cents, never floats
## Never
- Edit files in `src/generated/` (run `pnpm codegen` instead)
- Add a dependency without asking
## Details
- Database rules: @docs/database.mdWhat to keep out of it
- Anything long. Anthropic recommends staying under 200 lines per file: longer files take more context and are followed less reliably.
- Rules for one part of the code. Put them in .claude/rules/ with a paths field, so they load only when Claude works on matching files.
- Secrets. API keys and passwords have nothing to do in a file loaded into every conversation, and often committed.
- A diary of decisions. “Why we switched to Postgres”, “what the client said in March”: this grows without end and is not an instruction. It belongs in a memory Claude can search when it needs it, not in context every time.
Imports, rules and AGENTS.md
Imports. A line such as @docs/database.md pulls another file into context. Paths are relative to the file that contains the import, and imports can nest up to four hops. They organise a long file but do not make it cheaper: imported files load at launch too.
.claude/rules/. One Markdown file per topic (testing.md, api-design.md). A rule with a paths field in its frontmatter loads only when Claude touches matching files; personal rules for all projects go in ~/.claude/rules/.
AGENTS.md. If your repository already has an AGENTS.md for other coding agents, recent versions of Claude Code read it when there is no CLAUDE.md in the working directory or above it. If both exist, Claude reads CLAUDE.md; import AGENTS.md from it to keep a single source. Which other tools read it, and from where: the AGENTS.md guide.
CLAUDE.md, auto memory and a real memory
Claude Code also keeps auto memory: notes it writes itself from your corrections, in ~/.claude/projects/<project>/memory/, with a MEMORY.md index of which the first 200 lines or 25KB load at each session. Both stay on your machine, and both are tied to Claude Code.
The project-root CLAUDE.md survives /compact: Claude re-reads it from disk. An instruction given only in conversation does not. So the rule is simple: instructions go in CLAUDE.md; knowledge that keeps growing (decisions and their reasons, client context, what you tried) is better kept in a memory server that Claude searches when it needs it, and that your other AIs can read too.
Pryzm for desktop is one: a free app that keeps that memory in a SQLite file on your computer and connects Claude Code, Claude Desktop, Cursor and VS Code in one click. One line in ~/.claude/CLAUDE.md, such as “check Pryzm for past decisions before starting, and save new ones there”, is enough to make Claude use it. More in Claude Code memory.
Frequently asked questions
Where should I put CLAUDE.md?
At the root of your repository (./CLAUDE.md or ./.claude/CLAUDE.md) for project rules shared with your team, and in ~/.claude/CLAUDE.md for personal preferences across all projects. CLAUDE.local.md holds personal notes for one project.
How long should CLAUDE.md be?
Anthropic recommends under 200 lines per file. Move rules that apply to part of the code into .claude/rules/ with a paths field, so they load only when needed.
Does Claude Code read AGENTS.md?
Yes, in recent versions, when there is no CLAUDE.md in the working directory or above it. If both exist, it reads CLAUDE.md; you can import AGENTS.md from it.
Does CLAUDE.md survive /compact?
The project-root CLAUDE.md does: Claude re-reads it from disk after compaction. Instructions given only in the conversation can be lost.