Skip to content
Agent Friendly Code

CLAUDE.md: where it goes and what to put in it

CLAUDE.md is the Markdown file Claude Code loads into every session as project instructions. Put it at the repo root (or in .claude/), keep it under about 200 lines of concrete commands and conventions, and move what matters only for part of the codebase into .claude/rules/ or a nested CLAUDE.md.

What is CLAUDE.md?

A plain Markdown file Claude Code reads at the start of every session: build and test commands, where things live, the conventions a reviewer would otherwise repeat. No required structure, no frontmatter.

Claude treats it as context, not enforced configuration. What must happen every time, such as a check before each commit, belongs in a hook; what must never happen, in permissions.deny.

In our census of the 388 GitHub repos on the board on 2026-11-16, 128 have a CLAUDE.md somewhere in the tree and 110 have one at the root (census counts include empty files and symlinks). 59 keep one in a subdirectory.

Where does CLAUDE.md go?

CLAUDE.md locations in Claude Code, broadest scope first
ScopeLocationShared with
Managed policymacOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux and WSL /etc/claude-code/CLAUDE.md, Windows C:\Program Files\ClaudeCode\CLAUDE.mdEveryone on the machine; can't be excluded
User (global)~/.claude/CLAUDE.md, plus ~/.claude/rules/Only you, in every project
Project./CLAUDE.md or ./.claude/CLAUDE.md, plus .claude/rules/The team, through git
Local./CLAUDE.local.md, added to .gitignoreOnly you, in this project
Subdirectorypackages/web/CLAUDE.md and so onThe team; loads on demand

At launch Claude Code loads CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it, joined root first, so a project instruction lands after a user one. A subdirectory's CLAUDE.md loads once Claude reads, writes or edits a file there. Files that load on demand are capped at 40,000 characters each on a 200K context window; past that Claude gets only the start.

CLAUDE.local.md loads alongside CLAUDE.md and is treated the same; it's for your sandbox URLs and test data. Trap: it counts as a CLAUDE.md, so adding one stops Claude Code reading the repo's AGENTS.md in its place.

How do you write a good CLAUDE.md?

  • Write instructions concrete enough to check: "Run npm test before committing", not "Test your changes"; "API handlers live in src/api/handlers/", not "Keep files organized".
  • Group lines under headings and bullets; Anthropic's docs say Claude follows organised sections better than dense paragraphs.
  • Remove contradictions: of two conflicting instructions, Claude may pick either. /doctor prompt-audit (v2.1.283 and later) reports stale and conflicting lines across your instruction files without editing them.
  • Leave out what Claude finds by reading the code. The file is for what it can't discover: the one test command that works, the directory nobody should touch.
  • Block-level HTML comments are stripped before the file reaches Claude, so maintainer notes cost no context.

/init drafts one from the codebase (build commands, test instructions, conventions it finds); where a CLAUDE.md exists it suggests improvements instead of overwriting. With CLAUDE_CODE_NEW_INIT=1 it also reads AGENTS.md, .devin/rules/, .windsurf/rules/, .windsurfrules and .clinerules and folds in what applies.

CLAUDE.md (starter template)

# CLAUDE.md

<!-- Stripped before Claude reads it: notes for maintainers go here. -->

## Commands
- Install: `pnpm install`
- Test one file: `pnpm test path/to/file.test.ts`
- Lint and types: `pnpm lint && pnpm typecheck` (run both before committing)

## Layout
- `src/api/handlers/`: HTTP handlers, one file per route
- `src/db/`: the only place SQL is written

## Conventions
- Use 2-space indentation and named exports.
- New endpoints need a test in `tests/api/`.

## Don't
- Edit `src/generated/`; run `pnpm codegen` instead.

How long should CLAUDE.md be?

Anthropic's target is under 200 lines per file: longer files use more context and are followed less closely. The only hard limit: Claude Code skips a file over 4 MiB. Splitting into @imports tidies a file but saves nothing, since imports load with the file that imports them. What saves context is moving rules for part of the codebase into path-scoped .claude/rules/ files or subdirectory CLAUDE.md files, which load only when Claude works there.

For scale: the median AGENTS.md or CLAUDE.md across the 226 board repos that have one is 6,942 characters.

How does the CLAUDE.md import syntax work?

Write @path/to/file anywhere in a CLAUDE.md and that file is expanded into context beside it. Relative paths resolve from the importing file, not the working directory; absolute and ~/ paths work too. Imports can nest up to four hops. A path in a code span or fenced block isn't imported, so backticks keep it as text. The first time a project imports a file from outside the working directory, Claude Code asks you to approve it.

CLAUDE.md with imports

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

## Git workflow
@docs/git-workflow.md

## Personal notes, shared across worktrees
@~/.claude/my-project-notes.md

The import we count is @AGENTS.md: 39 of the 388 repos in our census keep their shared rules in AGENTS.md and import it from CLAUDE.md. The one-file guide covers that setup.

How do .claude/rules files work?

Every .md file under .claude/rules/ is found recursively. A rule without frontmatter loads at launch with the same priority as .claude/CLAUDE.md. A rule with a paths: glob list loads only when Claude reads, writes or edits a matching file, so it costs nothing in sessions that never touch those files. ~/.claude/rules/ does the same for every project on your machine.

.claude/rules/api.md

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

# API rules

- Validate every request body with the schema in `src/api/schemas/`.
- Return errors in the shape of `ApiError`.

Rules still load every session or on every matching file. For a procedure Claude needs only sometimes, like cutting a release, a skill is cheaper: see AGENTS.md vs skills.

How do you check which CLAUDE.md files loaded?

  • /memory lists the CLAUDE.md, CLAUDE.local.md and other memory files in use, and opens one to edit.
  • /context all shows the loaded files under Memory files.
  • The InstructionsLoaded hook logs which CLAUDE.md and rules files load, when and why: useful for path-scoped rules and subdirectory files.
  • In a monorepo, the claudeMdExcludes setting skips other teams' CLAUDE.md files by path or glob. It can't exclude the managed file.

What do real CLAUDE.md files look like?

Board repos where CLAUDE.md is the instructions file our scorer reads (it prefers AGENTS.md when both have content, so repos with both are under AGENTS.md examples). Each shows the layout a maintained project settled on.

Repos on the board with a CLAUDE.md
RepoFileLength
react/reactCLAUDE.md 358
anthropics/claude-codeCLAUDE.md 2,217
denoland/denoCLAUDE.md 11,861
hiyouga/LlamaFactoryCLAUDE.md 3,901
jestjs/jestCLAUDE.md 45
chakra-ui/chakra-uiCLAUDE.md 9,339
koalaman/shellcheck.claude/CLAUDE.md 3,892
qdrant/qdrantCLAUDE.md 5,588
surrealdb/surrealdbCLAUDE.md 6,080
labstack/echoCLAUDE.md 3,132

Questions people ask

Where is the global CLAUDE.md?
~/.claude/CLAUDE.md. It applies to every project on your machine and loads before the project's files; neither overrides the other. Personal path-scoped rules go in ~/.claude/rules/.
CLAUDE.local.md vs CLAUDE.md: which one?
CLAUDE.md is committed and shared with the team. CLAUDE.local.md sits at the project root, is gitignored, and holds what only you need. Both load together, and a CLAUDE.local.md stops Claude Code falling back to the repo's AGENTS.md.
Is there a CLAUDE.md size limit?
None you'll hit: Claude Code skips only files over 4 MiB. The guidance is under 200 lines per file, and files that load on demand are cut at 40,000 characters on a 200K context window.
CLAUDE.md vs AGENTS.md: do I need both?
Not usually. Claude Code reads AGENTS.md only when no CLAUDE.md exists; most other agents read AGENTS.md, only some CLAUDE.md. Keep shared rules in AGENTS.md and import it from CLAUDE.md or symlink CLAUDE.md to it. Full comparison: the CLAUDE.md vs AGENTS.md page.
Does /init overwrite an existing CLAUDE.md?
No. It suggests improvements instead.
Can CLAUDE.md enforce a rule?
No. It's context Claude weighs, not configuration it must obey. To guarantee something runs, use a hook; to block an action, use permissions.deny in settings.
What is the Karpathy CLAUDE.md?
A single CLAUDE.md published on GitHub as andrej-karpathy-skills. Its README says it is "derived from Andrej Karpathy's observations on LLM coding pitfalls"; Karpathy didn't write it. It sets four principles: think before coding, simplicity first, surgical changes, goal-driven execution. Behaviour rules like these complement, not replace, the project facts (commands, layout) a CLAUDE.md is for.

From the docs: code.claude.com/memory (new tab) · github.com/andrej-karpathy-skills (new tab)

CLAUDE.md vs AGENTS.md · One file for every agent · AGENTS.md vs skills · AGENTS.md examples · Check your AGENTS.md · All guides