# What goes in a CLAUDE.md file?

> A CLAUDE.md file holds a project's test and build commands, the conventions that break the defaults and the known gotchas. Claude Code reads it at the start of every session, and Anthropic suggests keeping each file under 200 lines. Run `/init` for a first draft, then cut every line Claude could learn by reading the code.

Mindket editors · Published 2026-10-22 · Updated 2026-11-03 · https://mindket.com/blog/claude-md-file

## In short

- Add a line when Claude makes the same mistake twice, by saying "add this to CLAUDE.md" rather than "remember this".
- When two of your CLAUDE.md files disagree, delete one line. The nearer file doesn't win.
- A rule that must never break, like keeping Claude out of `.env`, goes in a deny rule or a hook.

## 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](https://code.claude.com/docs/en/best-practices) 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](https://code.claude.com/docs/en/memory) 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.

[![Boris Cherny (@bcherny) on X, 2 January 2026, replying to a question about the size of his file. Our checked in CLAUDE.md is 2.5k tokens. It covers common bash commands, code style conventions, UI and content design guidelines, how to do state management, logging, error handling, gating and debugging, and a pull request template.](https://mindket.com/blog/shots/x-bcherny-claude-md-2-5k-tokens.webp?v=0ba566898210)](https://x.com/bcherny/status/2007212366094811401)

Boris Cherny on X, 2 January 2026

> 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.

````markdown
# 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](https://code.claude.com/docs/en/memory)), 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 |

[![Boris Cherny (@bcherny) on X, 27 January 2026, replying to Charles Frye, who called loading every CLAUDE.md up the tree and down it a crazy policy. Ancestor CLAUDE.md files load into context automatically on startup. Descendant ones load lazily, only when Claude reads or writes files in their folder.](https://mindket.com/blog/shots/x-bcherny-claude-md-loading.webp?v=1bd4732dfe44)](https://x.com/bcherny/status/2016339448863355206)

Boris Cherny on X, 27 January 2026

> 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](https://code.claude.com/docs/en/features-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.
>
> Anthropic, The "When to add to CLAUDE.md" list in its memory guide, [Claude Code docs: How Claude remembers your project](https://code.claude.com/docs/en/memory) (read 2026-11-03)

## 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](https://code.claude.com/docs/en/best-practices). 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](https://mindket.com/blog/what-are-agent-skills), a folder with a SKILL.md file under `.claude/skills/`. [Claude Code loads a skill's description every session](https://code.claude.com/docs/en/skills) and reads the full file only when the task calls for it.

[Subagents](https://mindket.com/blog/claude-code-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](https://code.claude.com/docs/en/sub-agents), 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.

**Three sizes to check a CLAUDE.md against**

- **2.5k** tokens in the CLAUDE.md that Claude Code's creator, Boris Cherny, says his team checks in (Source: [Boris Cherny on X](https://x.com/bcherny/status/2007212366094811401), read 2026-11-03)
- **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](https://code.claude.com/docs/en/memory), read 2026-11-03)
- **40,000** characters per file that loads on demand, on a 200K context window (Source: [Claude Code docs: How Claude remembers your project](https://code.claude.com/docs/en/memory), read 2026-11-03)

**Where each kind of instruction goes**

| | 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](https://code.claude.com/docs/en/memory) (read 2026-11-03), [Claude Code docs: Best practices](https://code.claude.com/docs/en/best-practices) (read 2026-11-03), [Claude Code docs: Extend Claude with skills](https://code.claude.com/docs/en/skills) (read 2026-11-03)

> 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](https://code.claude.com/docs/en/memory) 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) (read 2026-11-03)
- [Claude Code docs: Best practices](https://code.claude.com/docs/en/best-practices) (read 2026-11-03)
- [Claude Code docs: Extend Claude Code](https://code.claude.com/docs/en/features-overview) (read 2026-11-02)
- [Claude Code docs: Extend Claude with skills](https://code.claude.com/docs/en/skills) (read 2026-11-02)
- [Claude Code docs: Create custom subagents](https://code.claude.com/docs/en/sub-agents) (read 2026-11-02)
- [Boris Cherny on X: the Claude Code team's checked-in CLAUDE.md is 2.5k tokens](https://x.com/bcherny/status/2007212366094811401) (read 2026-11-03)
- [Boris Cherny on X: which CLAUDE.md files load at startup and which load later](https://x.com/bcherny/status/2016339448863355206) (read 2026-11-03)

[Create an Agent Skill](https://mindket.com/blog/how-to-create-agent-skill)