CLAUDE.md: How to Write One That Claude Code Actually Follows (2026 Guide)
Quick answer: A CLAUDE.md file is a plain Markdown file Claude Code reads at the start of every session. Put build commands, conventions and "always do X" rules in it, keep each file under about 200 lines, and run
/initto generate a first draft.Treat it as guidance, not enforcement. If something must happen every time, use a hook instead.
Every Claude Code session starts with an empty context window. Claude does not remember that your team uses pnpm, that tests live in tests/, or that you never touch the billing module without review. A CLAUDE.md file is where you write those facts down once so you stop retyping them.
This guide covers what to put in the file, where Claude looks for it, and the mistakes that make it ignored. Everything below was checked against Anthropic's memory documentation on November 19, 2026. Details such as version numbers change, so check the docs if you run an older version.
What is a CLAUDE.md file?
CLAUDE.md is a Markdown file that gives Claude persistent instructions for a project, for you personally, or for your whole organization. You write it in plain text, and Claude reads it at the start of each session.
It is one of two memory systems in Claude Code. The other is auto memory, where Claude writes its own notes from your corrections.
| CLAUDE.md | Auto memory | |
|---|---|---|
| Who writes it | You | Claude |
| What it holds | Instructions and rules | Learnings and patterns |
| Scope | Project, user or organization | Per repository |
| Loaded | Every session | Every session (first 200 lines or 25KB) |
Use CLAUDE.md when you want to steer Claude's behavior. Let auto memory handle the small stuff Claude picks up from your corrections.
Where Claude looks for CLAUDE.md files
Files can live in several places, and each has a different audience. The docs list them from broadest to most specific:
| Scope | Location | Shared with |
|---|---|---|
| Managed policy | /Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux and WSL), C:\Program Files\ClaudeCode\CLAUDE.md (Windows) | Everyone in an organization |
| User | ~/.claude/CLAUDE.md | Just you, all projects |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md | Your team, through git |
| Local | ./CLAUDE.local.md | Just you, this project |
A few details matter in practice:
- Claude loads
CLAUDE.mdandCLAUDE.local.mdfrom your working directory and every directory above it. Files are combined, not overridden. - Files in subdirectories load on demand, when Claude reads files in those folders.
- Add
CLAUDE.local.mdto your.gitignore. It is for personal notes such as sandbox URLs. - For large monorepos where other teams' files get picked up, the
claudeMdExcludessetting lets you skip them.
What to put in it
Anthropic's guidance is to treat CLAUDE.md as the place you write down what you would otherwise re-explain. Add a line when:
- Claude makes the same mistake a second time.
- A code review catches something Claude should have known about your codebase.
- You type the same correction you typed last session.
- A new teammate would need the same context to be productive.
Good entries are specific and checkable:
- "Use 2-space indentation" instead of "Format code properly."
- "Run
npm testbefore committing" instead of "Test your changes." - "API handlers live in
src/api/handlers/" instead of "Keep files organized."
Here is a small example for a US startup's web app:
# Project notes
## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Lint: `pnpm lint` (must pass before any commit)
## Conventions
- TypeScript strict mode, 2-space indentation
- API handlers live in `src/api/handlers/`
- Currency is stored in cents; display in US dollars
## Rules
- Never edit files in `migrations/` without asking first
- Use American English in user-facing copy
Notice what is missing: long explanations, history, and anything Claude can read straight from the code. The docs' own /doctor check trims exactly that kind of content, such as directory layouts and dependency lists that Claude can derive from the repository.
Start with /init
You do not have to write the first version from scratch. Run /init in Claude Code and it analyzes your codebase and generates 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.
Then edit it by hand. The most valuable lines are the ones Claude could not discover on its own, like "we deploy on Fridays only after QA signs off."
Keep it short
This is the rule people skip. Anthropic recommends targeting under 200 lines per CLAUDE.md file. Longer files use more context and can reduce how well Claude follows them. Claude Code even shows a warning at startup and in /status when a file runs long.
If your file is growing, you have three options:
- Move instructions to path-scoped rules. Put them in
.claude/rules/with apathsfield so they load only when Claude touches matching files. - Move procedures to a skill. A multi-step workflow that matters only sometimes belongs in a skill, which loads when needed. See what Claude skills are and how to create your own.
- Cut it. If Claude would do the right thing without the line, delete the line.
Imports help with organization but not with size. The docs are explicit that imported files still load into context at launch, so splitting one file into five does not save space.
Imports and the rules folder
CLAUDE.md can pull in other files with an @ path:
See @README for the project overview and @package.json for npm commands.
- Git workflow: @docs/git-instructions.md
Relative paths resolve from the file that contains the import, and imports can chain up to four hops deep. Writing a path in backticks keeps it literal instead of importing it.
For bigger projects, use .claude/rules/. Each Markdown file covers one topic, such as testing.md or security.md. A rule with no paths field loads every session. A rule with a paths field loads only when Claude reads, writes or edits a matching file:
---
paths:
- "src/api/**/*.ts"
---
# API rules
- Every endpoint validates its input
- Use the standard error response format
Personal rules that apply to every project can go in ~/.claude/rules/.
What about AGENTS.md?
Many repos already have an AGENTS.md for other coding agents. According to the docs, Claude Code can read it directly (version 2.1.277 or later), but with a catch: by default it reads AGENTS.md only when there is no CLAUDE.md in your working directory or above it.
If you want both, create a short CLAUDE.md that imports the other file:
@AGENTS.md
That way Claude Code picks up the same instructions your other agent tools use. For how those tools handle skills, see our guides to Cursor skills and Codex skills.
CLAUDE.md is guidance, not a guardrail
Anthropic is direct about this: Claude treats CLAUDE.md as context, not enforced configuration. The content arrives as a user message after the system prompt, so there is no guarantee of strict compliance, especially with vague or conflicting instructions.
That has a practical consequence. Do not rely on CLAUDE.md for anything with real consequences, like keeping secrets out of commits. For rules that must hold every time, the docs point to hooks, which run as shell commands at fixed points and apply no matter what Claude decides. Our guide to Claude Code hooks shows how.
For a side-by-side view of hooks, skills and subagents, read subagents vs skills vs hooks vs commands vs plugins.
Troubleshooting
If Claude seems to ignore your file, work through this list:
- Run
/contextand check the Memory files list to confirm your file actually loaded. - Make instructions more specific. Concrete beats vague.
- Look for contradictions between your user file, project file and rules. Claude may pick one arbitrarily.
- Use
/memoryto open and edit the loaded files. - Run
/doctor prompt-auditto have Claude flag outdated or conflicting instructions. The docs say it needs Claude Code v2.1.283 or later.
A final tip from the docs: block-level HTML comments (<!-- note -->) are stripped before the file is sent to Claude, so you can leave maintainer notes without spending context.
FAQ
What is CLAUDE.md? A Markdown file of persistent instructions that Claude Code reads at the start of every session. It can be personal, shared with your team, or managed for an organization.
Where should I put CLAUDE.md? For a team project, put it at the repository root as ./CLAUDE.md or in ./.claude/CLAUDE.md and commit it. For personal preferences across all projects, use ~/.claude/CLAUDE.md.
How long should a CLAUDE.md be? Anthropic recommends under 200 lines per file. Move the rest into .claude/rules/ files or skills.
Does Claude read AGENTS.md? Yes, in recent versions, but by default only when no CLAUDE.md exists. Import it from a CLAUDE.md if you want both.
Is CLAUDE.md enforced? No. It shapes behavior but does not guarantee it. Use hooks or permission settings for hard rules.
Should I commit CLAUDE.md to git? Commit the project file so your team shares it. Keep CLAUDE.local.md out of version control.
Sources: How Claude remembers your project (Anthropic documentation).