CLAUDE.md guide: how to write one Claude follows

CLAUDE.md is a Markdown file of instructions that Claude Code reads at the start of every session. Put it at the root of your repository and keep it short: the exact commands, conventions and corrections Claude can't work out from the code. Run /init to generate a first draft, then cut every line Claude doesn't need.

What is CLAUDE.md?#

Every Claude Code session starts with a fresh context window, and CLAUDE.md carries what Claude should know about your project from one session to the next. Claude treats it as context, not enforced configuration, so the more specific and concise the file, the more consistently Claude follows it.

Where does CLAUDE.md go?#

The location decides who gets the instructions:

Claude Code loads CLAUDE.md and CLAUDE.local.md from the directory where you start it and every directory above it, and joins them rather than letting one override another. A file in a subfolder, such as packages/api/CLAUDE.md, loads once Claude works on a file in that folder. Run /context and look under Memory files to see what loaded.

How do you create a CLAUDE.md?#

Run /init in your project. Claude reads the codebase and writes a first CLAUDE.md with build commands, test instructions and the conventions it finds, or suggests improvements to an existing one. It also carries over rules you wrote for other tools, such as .cursorrules. From there the work is mostly removing lines.

For a guided version, start Claude Code with CLAUDE_CODE_NEW_INIT=1 claude and run /init: it asks follow-up questions and shows a proposal before it writes anything.

What should go in CLAUDE.md?#

Every line takes a little of Claude's attention on every task, so keep only what Claude can't work out from the code:

• How to check work: the exact test, typecheck and lint commands, and how to run one test file.
• Where the code misleads: an old pattern that new code must not copy, or a folder that looks unused but isn't.
• Decisions that aren't in the repository: which error helper the team chose, how deploys work, what needs a migration review.
• Corrections you've made twice.

Leave out directory layouts and dependency lists, which Claude reads from the repository. Some lines belong somewhere else:

A CLAUDE.md template#

Anthropic's best-practices guide gives this short file as an example. Replace the commands and rules with your own:

# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit

# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code

# Gotchas
- Integration tests need DATABASE_URL set, see .env.example

The typecheck line is only the command, so Claude can check its own work. "Always typecheck before you finish" works most of the time, not every time; to enforce it, use a Stop hook.

Write each line so you could verify it:

Keep the file under about 200 lines, grouped under headers and bullets, and run /doctor prompt-audit now and then to find stale or conflicting instructions.

Imports and path rules#

A CLAUDE.md can pull in another file with an @path line, such as - Git workflow: @docs/git-instructions.md. Relative paths resolve from the file that holds the import, and a path inside backticks stays plain text instead of an import. Imports organize a long file but don't lower its context cost, because the imported text loads with it.

To load a rule only where it applies, put it in .claude/rules/ with a paths field. Without paths, a rule loads at launch like CLAUDE.md:

---
paths:
  - "src/api/**/*.ts"
---
- Validate request bodies with the zod schemas in src/api/schemas/, don't hand-roll checks
- Every new endpoint needs an entry in openapi.yaml, CI fails without it

Does Claude Code read AGENTS.md?#

Yes, from version 2.1.277, so a repository set up for other coding agents works without a CLAUDE.md. By default:

Your ~/.claude/CLAUDE.md and .claude/rules/ don't count for that check. A CLAUDE.local.md does, so adding one for your own notes stops Claude from reading the team's AGENTS.md. To have Claude read both, type /config and set Project instructions to claude-md-and-agents-md.

With a custom base URL, as on a 5abeer key, this needs version 2.1.281 or later, the release that brought AGENTS.md support to LLM gateways. On older versions, or to add lines only Claude needs, start a CLAUDE.md with an import:

@AGENTS.md

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

Common CLAUDE.md mistakes#

• A long file. Past about 200 lines, single lines get lost. Move procedures into skills and folder rules into .claude/rules/.
• Contradictions. When two lines disagree, Claude may pick either one, so read all your instruction files together.
• Emphasis instead of a fix. IMPORTANT or capital letters rarely help current models and mostly make Claude over-apply the rule.
• Rules that must never bend. "Never read .env" works almost every time, not every time. Use a deny rule or a hook for those.

CLAUDE.md or auto memory?#

You write CLAUDE.md. Auto memory is the notes Claude writes for itself, such as corrections you gave, in ~/.claude/projects/<project>/memory/. Claude Code loads your CLAUDE.md in full, but only the first 200 lines or 25KB of the memory index, MEMORY.md. Auto memory stays on your machine, so your team never sees it.

Say "remember that the API tests need a local Redis" and Claude saves it to auto memory; say "add this to CLAUDE.md" to put it in the file. /memory opens both and turns auto memory on or off. For skills, hooks and subagents side by side, see Claude Code skills.

Does CLAUDE.md add to the cost?#

A little. On an API key, its text is ordinary input on every task, billed per token at the model's price. Block-level HTML comments are removed before the file reaches Claude, so notes you leave there cost nothing. The current price of the default model:

CLAUDE.md through 5abeer#

5abeer is an independent service, not affiliated with Anthropic. Its API follows the Anthropic Messages format, so Claude Code works with it as it ships, and both routes cost less than the official price. CLAUDE.md is a file on your machine, so it works the same on a 5abeer key; only the base URL and key change.

With an API key: create a key for Claude models, then set the base URL and key in Claude Code's settings:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.5abeer.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_5ABEER_API_KEY",
    "ANTHROPIC_MODEL": "claude-sonnet-5.5"
  }
}

Every request is deducted from your balance by model and token count, and you control each key with a spend limit, an expiry date and an IP allow-list. The full setup is in Claude Code setup, and prices are on Claude API.

The Messages API doesn't read CLAUDE.md, so from your own code, send the same rules in the request's system field, as in Anthropic Messages.

With a plan: the 5abeer AI app turns Claude Code on for your plan in one click, with no key and no files to edit. The plan runs with a 5-hour limit and a weekly limit, as in Subscription limits. Plans are for the supported apps, and to use the models from your own code you need an API key. See What each plan runs and the pricing page.

FAQ#

Does the file have to be called CLAUDE.md?#

Yes, or CLAUDE.local.md for your own notes. Claude Code also reads AGENTS.md when there is no CLAUDE.md. Any other file loads only through an @path import or from .claude/rules/.

Should CLAUDE.md go in git?#

The project file, yes: committing it gives your team the same instructions. Keep personal notes in CLAUDE.local.md, listed in .gitignore. That file exists only in the worktree where you made it, so across worktrees, import one from your home folder, such as @~/.claude/my-project-instructions.md.

How long should CLAUDE.md be?#

Under about 200 lines, as Anthropic recommends; Claude Code warns at startup and in /status when a file runs longer. Subfolder files and path rules, which load on demand, are cut at 40,000 characters on a 200K context window.

Why does Claude ignore my CLAUDE.md?#

Run /context. If a file that should load at launch isn't under Memory files, check its name and location. If it loaded, make the line more specific, remove anything that contradicts it, and shorten the file. A rule that must hold every time belongs in a hook.

Does CLAUDE.md survive /compact?#

The project-root CLAUDE.md does: Claude Code reads it again from disk after /compact. Subfolder files and path rules return when Claude next works on a matching file. Instructions you gave only in the chat can be lost, so put the ones you want kept in the file.

Sources#

Checked on 2 November 2026.

• Claude Code docs: How Claude remembers your project
• Claude Code docs: Best practices for Claude Code
• Claude Code changelog, versions 2.1.277 and 2.1.281

Get started#

To compare plans and keys for Claude Code, read The cheapest way to use Claude Code, or set up Claude Code now.