The CLAUDE.md File, Explained

What a CLAUDE.md File Is

Every Claude Code session starts with an empty context window. A CLAUDE.md is the Markdown file Claude Code loads into that window first, so the things you would otherwise re-explain each session are already there: how to build and test, how the code is organised, and what your team does differently from the defaults.

There is no schema and no required section. It is ordinary headings, bullet lists and inline code, and Anthropic's guidance is to use exactly that: group related instructions under headings, one instruction per bullet, rather than dense paragraphs.

A CLAUDE.md Example

A realistic project file. Each line is something Claude could not reliably infer by reading the repo. The HTML comment is a note for humans: Claude Code strips it before Claude sees the file.

# Acme Web

<!-- Owners: platform team. Keep under 200 lines; move
     area-specific rules to .claude/rules/. -->

See @README.md for the project overview and
@package.json for scripts.

## Commands
- `pnpm dev` starts the app on :3000
- `pnpm test` runs Vitest; run it before every commit
- `pnpm lint` must pass clean, no eslint-disable

## Conventions
- TypeScript, 2-space indent, no default exports
- API handlers live in `src/api/handlers/`
- Use the `Result` type in `src/lib/result.ts`, never throw

## Gotchas
- Integration tests need Redis: `docker compose up redis`
- Never edit `src/generated/`; run `pnpm codegen`

Where the CLAUDE.md File Goes

There are four locations, from broadest to most specific. Claude Code loads all that exist; none replaces another.

Working across several git worktrees? A gitignored CLAUDE.local.md only exists in the worktree you created it in. Keep the personal file in your home directory and import it instead: @~/.claude/my-project.md.

The Order CLAUDE.md Files Load In

Claude Code walks from the filesystem root down to the folder you launched in and concatenates every CLAUDE.md and CLAUDE.local.md it finds. Nothing overrides anything; the closest file is simply read last.

1. Managed policy CLAUDE.md        ← org-wide, always first
2. ~/.claude/CLAUDE.md             ← you, every project
3. ~/code/acme/CLAUDE.md           ← repo root
4. ~/code/acme/CLAUDE.local.md     ← you, this repo
5. ~/code/acme/apps/web/CLAUDE.md  ← read last at launch

Later, on demand:
   ~/code/acme/apps/web/src/payments/CLAUDE.md
   ← loads the first time Claude reads or edits
     a file in src/payments/

In a monorepo where other teams' files get picked up, skip them with claudeMdExcludes, a list of globs matched against absolute paths, ideally in .claude/settings.local.json. The managed policy file can't be excluded.

Markdown That Behaves Differently in CLAUDE.md

CLAUDE.md is ordinary Markdown with a few additions. These are the pieces that do something in Claude Code that they would not do in a README.

@imports

An @path anywhere in the text pulls that file into context at launch, alongside the CLAUDE.md that names it. Paths are relative to the importing file, not your working directory. Absolute and ~ paths work, and imported files can import others, up to four hops.

See @README.md for the overview and @package.json for scripts.

## More instructions
- Git workflow: @docs/git-instructions.md
- API style: @Design\ Docs/api-conventions.md

To mention a file without loading it, use backticks: `@docs/old.md`

Two things to know. Imports organise a long file but don't shrink it, because everything imported still loads at launch. And an import that resolves outside the project shows a one-time approval dialog; decline it and those imports stay off for that project.

HTML comments are free

A block-level Markdown comment (<!-- ... --> on its own lines) is stripped before the file is injected, so you can leave notes for the humans who maintain the file without spending a single token on them. A comment inside a code block is kept. If Claude opens the file with its Read tool, it sees the comments.

Splitting It Up With .claude/rules/

For larger projects, put one topic per Markdown file in .claude/rules/ (subfolders are fine). A rule with no front matter loads at launch like .claude/CLAUDE.md. Add a paths field and it only loads when Claude reads, writes or edits a matching file, which is how you shrink the context cost.

---
paths:
  - "src/api/**/*.ts"
  - "tests/api/**/*.test.ts"
---

# API rules

- Validate every request body with zod
- Return errors in the shape from src/api/errors.ts

paths is the only field Claude Code reads; any other key is ignored. Globs support ** and brace expansion like src/**/*.{ts,tsx}. If the YAML doesn't parse, the rule loads as if it had no paths. Personal rules for every project go in ~/.claude/rules/ and load before the project's.

CLAUDE.md vs AGENTS.md

AGENTS.md is the cross-tool version of the same idea, read by Codex, Cursor, Copilot and others. Since v2.1.277 Claude Code reads it too, but by default only as a fallback:

If your team uses several agents, keep AGENTS.md as the shared file and make the CLAUDE.md a thin wrapper:

@AGENTS.md

## Claude Code
Use plan mode for changes under src/billing/.

Note that adding a personal CLAUDE.local.md to a repo that relies on AGENTS.md stops Claude reading AGENTS.md for you. To read both without an import, set Project instructions to claude-md-and-agents-md in /config.

Commands for Working With CLAUDE.md

Asking Claude to “remember” something saves it to auto memory, a separate, machine-local store under ~/.claude/projects/. To put it in CLAUDE.md where your team will see it, say “add this to CLAUDE.md”. Source for everything on this page: Claude Code memory docs.

Common Mistakes

The patterns that make a CLAUDE.md cost more context and get followed less.

Frequently Asked Questions