What goes in: what Claude can't see in the code
Run /init in your project, and Claude reads the codebase and writes a first CLAUDE.md. Then start deleting, as Anthropic's best-practices page advises. A list of your folders can go first, since Claude can open the folders itself.
Each session starts with a fresh context window and loads the whole file at launch, whatever the task. So a note about deploys takes up context while Claude fixes your CSS.
Anthropic's memory guide sets "Use 2-space indentation" against "Format code properly", and "Run npm test before committing" against "Test your changes". The first line of each pair works because you could check whether Claude followed it.
- The exact test, typecheck and lint commands, and how to run a single test file.
- Places where the code misleads: an old pattern that is everywhere but must not be copied, a directory that looks unused but isn't.
- Decisions that aren't in the repository, such as which error helper the team settled on or what needs a migration review.
A screenshot of X's own embed of the post, taken on 3 November 2026, in US Pacific time and without the link preview. Select it to open the post on X.
A short sample CLAUDE.md
We wrote this one for a small TypeScript API, with headings that follow the split on Anthropic's best-practices page. Save it as CLAUDE.md in the project root.
# Commands
- Install: npm ci
- Run one test file: npx vitest run path/to/file.test.ts
- Typecheck: npx tsc --noEmit
# Conventions
- API handlers live in src/api/handlers/, one file per route
- Throw the error classes in src/lib/errors.ts, never raw strings
- src/legacy/ is still live. Do not copy its patterns into new code
# Gotchas
- Integration tests need DATABASE_URL set, see .env.example
- Git workflow: @docs/git-workflow.md
Where CLAUDE.md files live and how they load
Say you start Claude Code in foo/bar/. It loads CLAUDE.md and CLAUDE.local.md from that directory and every one above it, foo/CLAUDE.md first and foo/bar/CLAUDE.md after, so the file closest to you comes last. Files in subfolders below foo/bar/ load later, once Claude reads or edits a file there.
The files are joined end to end, and none overrides another. Your project file lands after your user file (memory guide), yet when the two disagree, Claude may follow either one.
The sample's last line, @docs/git-workflow.md, is an import. The imported file loads along with the one that imports it, so splitting a file into imports saves no context. Block-level HTML comments such as <!-- maintainer notes --> are another matter: they're stripped before the file reaches Claude, so a note for people costs nothing.
A gitignored CLAUDE.local.md exists only in the git worktree where you created it. For personal instructions in every worktree, keep them in a file in your home directory and import that, for example @~/.claude/my-project-instructions.md.
| Scope | Location | Shared with |
|---|---|---|
| Managed policy | macOS: /Library/Application Support/ClaudeCode/CLAUDE.md. Linux and WSL: /etc/claude-code/CLAUDE.md. Windows: C:\Program Files\ClaudeCode\CLAUDE.md | Every user in the organization |
| User | ~/.claude/CLAUDE.md | Only you, in all projects |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md | Your team, through source control |
| Local | ./CLAUDE.local.md, added to .gitignore | Only you, in this project |
Taken the same way on the same day. X cuts this reply short with Show more, so open it on X to read the rest.
Adding and cutting lines with /init, /doctor and /memory
On a project that already has a CLAUDE.md, /init suggests improvements instead of overwriting it. It also reads Cursor rules in .cursor/rules/ or .cursorrules and Copilot rules in .github/copilot-instructions.md.
/doctor proposes cutting what Claude can derive from the code, such as directory layouts and dependency lists, and keeps pitfalls, rationale and conventions that differ from tool defaults. Its prompt-audit mode, which needs Claude Code v2.1.283 or later, also flags instructions written for older models, references to files or commands that don't exist, and files that contradict each other. It only reports: nothing changes until you ask Claude to apply its edits.
To edit by hand, /memory lists the CLAUDE.md and CLAUDE.local.md files for user and project scope, even ones that don't exist yet, and opens the one you pick in your editor. Or say "add this to CLAUDE.md" in the chat, which the extension overview recommends over typing the same correction once more.
A plain "remember this" goes to auto memory instead, a separate store that Claude writes, not you. It keeps notes such as your preferences and the corrections you gave, in one folder per repository under ~/.claude/projects/, shared by all of that repository's worktrees. Only the start of its MEMORY.md index loads each session, Claude reads the topic files on demand, and /memory switches it on and off.
When Anthropic says to add a line
Claude makes the same mistake a second time. A code review catches something Claude should have known about this codebase. You type the same correction or clarification into chat that you typed last session. A new teammate would need the same context to be productive.
What to leave out, and where it goes instead
Claude Code warns at startup when a file passes the recommended length. Capitalized emphasis can go first. Current models follow a plainly worded line, and piling on IMPORTANT mostly makes Claude over-apply the rule. Claude Code skips a file outright only past 4 MiB, and then loads none of it.
Say only the API code needs a rule. It goes in .claude/rules/ with a paths filter in its frontmatter that matches the TypeScript files under src/api/, and it loads only when Claude reads or edits one of them. Files that load on demand like this, subdirectory CLAUDE.md files included, stop at 40,000 characters each on a 200K context window. Past that, Claude receives only the start, and wc -m on the file tells you where you stand.
A long release procedure belongs in a skill, a folder with a SKILL.md file under .claude/skills/. Claude Code loads a skill's description every session and reads the full file only when the task calls for it.
Subagents you define start with your CLAUDE.md files in their context too, so a long file loads again on every delegation. The built-in Explore and Plan agents skip them, and a custom agent can opt out with omitClaudeMd: true.
"Never read .env" in a CLAUDE.md is followed almost every time, not every time. The file holds guidelines, and Claude may decide one doesn't apply. A deny rule such as Read(./.env) in your settings holds in every permission mode, and "Don't touch the migrations folder" becomes a PreToolUse hook that blocks edits under migrations/. We'd move a rule out only when one slip would leak a secret or damage data. The best-practices page warns against overdoing it: "Prefer named exports", with its many exceptions, stays in CLAUDE.md.
2.5k
tokens in the CLAUDE.md that Claude Code's creator, Boris Cherny, says his team checks in
Source: Boris Cherny on X (read November 3, 2026)
200
lines per file is Anthropic's target, because longer files use more context and reduce adherence
Source: Claude Code docs: How Claude remembers your project (read November 3, 2026)
40,000
characters per file that loads on demand, on a 200K context window
Source: Claude Code docs: How Claude remembers your project (read November 3, 2026)
| CLAUDE.md | A path-scoped rule | A skill | A hook or deny rule | |
|---|---|---|---|---|
| What it holds | Commands, conventions and gotchas | Rules for one part of the codebase | A long procedure for one kind of task | A rule with no exceptions |
| When it reaches Claude | At launch, every session | When Claude reads or edits a matching file | Its description every session, the rest when the task calls for it | On the event it watches, such as before each file edit |
| Takes up context on an unrelated task | Yes | No | Partly | No |
| Followed every time | No | No | No | Yes |
Sources: Claude Code docs: How Claude remembers your project (read November 3, 2026), Claude Code docs: Best practices (read November 3, 2026), Claude Code docs: Extend Claude with skills (read November 3, 2026)
Every fact here comes from the pages listed under Sources, read on November 2 and 3, 2026. It's a reading of the documentation, not hands-on testing, and file locations, commands and version requirements change between Claude Code releases.
Frequently asked questions
Is CLAUDE.md the same as AGENTS.md?
No. They are separate files, and Claude Code treats AGENTS.md as a fallback. Version 2.1.277 and later read it only when no CLAUDE.md or CLAUDE.local.md sits in your working directory or above it. To use both, put @AGENTS.md at the top of CLAUDE.md, and Claude reads the shared file first, then your Claude-specific lines. On Windows, Anthropic prefers that import to a symlink, because Git can check a committed symlink out as a one-line text file.
Why is Claude ignoring my CLAUDE.md?
First check that it loaded: run /context and look under Memory files. A CLAUDE.md in a subdirectory won't appear there until it loads on demand, and then a Loaded line shows its path. If it loaded, it may be too long, too vague or contradicted by another file. The file reaches Claude as a user message after the system prompt. The last of Anthropic's troubleshooting steps is to make the line more specific, like the indentation pair above.
Does CLAUDE.md survive /compact?
The project-root file does. After /compact, Claude re-reads it from disk and injects it again, while nested files and path-scoped rules load again on demand. An instruction you gave only in the conversation can disappear, so write it into the file if it has to last.
How do I skip another team's CLAUDE.md in a monorepo?
Add a claudeMdExcludes list of paths or glob patterns to .claude/settings.local.json, so the exclusion stays on your machine. Patterns match absolute file paths. A managed organization CLAUDE.md can't be excluded.
Sources
- Claude Code docs: How Claude remembers your project https://code.claude.com/docs/en/memory
- Claude Code docs: Best practices https://code.claude.com/docs/en/best-practices
- Claude Code docs: Extend Claude Code https://code.claude.com/docs/en/features-overview
- Claude Code docs: Extend Claude with skills https://code.claude.com/docs/en/skills
- Claude Code docs: Create custom subagents https://code.claude.com/docs/en/sub-agents
- Boris Cherny on X: the Claude Code team's checked-in CLAUDE.md is 2.5k tokens https://x.com/bcherny/status/2007212366094811401
- Boris Cherny on X: which CLAUDE.md files load at startup and which load later https://x.com/bcherny/status/2016339448863355206