Get the most from CoreCode

How to write CLAUDE.md

Last updated: October 27, 2026

CLAUDE.md is the project briefing Claude Code reads at the start of every session. Written well, Claude stops repeating mistakes; long and messy, it wastes context every turn. This page follows Anthropic's official guide, plus what it means for your bill.

What CLAUDE.md is

A plain Markdown file stating what Claude should know in this project: how to build and test, code conventions, the layout, "always do X" rules. Claude Code reads it at the start of every session as context.

It is not enforced configuration. The more specific and concise the rules, the more consistently Claude follows them; for something that must never happen, such as editing a protected directory, use a PreToolUse hook.

Claude Code also has auto memory: corrections you give it are saved under ~/.claude/projects/<project>/memory/. CLAUDE.md holds the rules you write, auto memory what Claude learns; both load every session.

Where it goes

At launch, Claude Code reads CLAUDE.md from the working directory and every directory above it, concatenated from the top down, so the file closest to where you started is read last. A CLAUDE.md in a subdirectory loads later, when Claude reads or edits a file in that subdirectory.

Where to start

Run /init in the project. Claude analyzes the codebase and writes a CLAUDE.md with build commands, test instructions and conventions it finds; if one exists, it suggests improvements instead of overwriting it. Then add what Claude could not discover on its own.

What to put in it

Treat it as the place for whatever you would otherwise explain again. Add a line when:

• Claude makes the same mistake a second time;
• a code review catches a convention Claude should have known;
• you type the same correction you typed last session;
• a new teammate would need the same context.

Keep to facts every session needs. Write multi-step procedures as skills, which load when needed, and put rules for one part of the codebase in .claude/rules.

How to write rules that work

Write rules you could check, not general wishes:

• Short. Keep each CLAUDE.md under 200 lines. Longer files take more context and are followed less well.
• Structured. Group related rules under headings, as bullets, not dense paragraphs.
• Consistent. When two rules conflict, Claude may pick either. Prune outdated entries; from Claude Code v2.1.283, /doctor prompt-audit finds outdated or conflicting entries and references to files that do not exist.
• Notes for humans as HTML comments. A <!-- note --> in CLAUDE.md is stripped before it reaches the context, so it costs no tokens.

A short example:

# Project

## Commands
- Install: pnpm install (not npm)
- Test: pnpm test, must pass before committing
- Run locally: pnpm dev, port 3000

## Conventions
- TypeScript strict mode, no any
- API handlers in src/api/handlers/, one route per file
- Schema changes only through prisma migrate

Importing other files

Pull in other files with @path, for example See @README and @docs/git-instructions.md. Relative paths resolve from the CLAUDE.md that contains them, and imports nest up to four levels. `@README` inside backticks is not imported.

Imports organize a file but do not reduce its context cost: imported content loads every time too. The first time a project imports a file outside its directory, Claude Code asks you to approve it.

Splitting by scope with .claude/rules

In a larger project, split instructions into topic files under .claude/rules/, such as testing.md or api-design.md. A rule without paths loads at launch like CLAUDE.md; one with paths loads only when Claude works on matching files:

---
paths:
  - "src/api/**/*.ts"
---
# API rules
- Validate every endpoint's input
- Return errors as ApiError

A section of CLAUDE.md that has grown into a multi-step procedure can become a skill, which loads only when used; see the skills guide.

If you already have AGENTS.md

From Claude Code v2.1.277, Claude reads AGENTS.md directly: without a CLAUDE.md it reads AGENTS.md, and with one it reads only CLAUDE.md. To share one file across coding tools, add a line @AGENTS.md to your CLAUDE.md.

Cost and caching

• It is sent every turn. CLAUDE.md, auto memory and rules without paths go out with every request. On a cache hit they cost the cache-read price, but the longer they are, the more a miss costs to rewrite. Another reason to keep them short.
• Mid-session edits wait. The running session does not see an edited CLAUDE.md until /clear, /compact or a restart (see Anthropic's Claude Code caching guide). In return, the edit does not invalidate the session's cache.

More ways to save are in Spending less on Claude Code.

How to confirm it loaded

• Run /context and look under Memory files. A file missing there is invisible to Claude.
• /memory lists, opens and edits each CLAUDE.md and toggles auto memory.

FAQ