CLAUDE.md: Standing Instructions for Claude Code

CLAUDE.md is a Markdown file of standing instructions that Claude Code reads at the start of every session. You write it: build and test commands, conventions, project layout, "always do X" rules. It is context, not enforcement, so Claude usually follows it but is not forced to. The Claude Code docs recommend keeping each file under 200 lines. Checked 31 October 2026.

At a glance

What it is

Claude Code's memory docs say every session starts with a fresh context window, and two mechanisms carry knowledge across sessions. One is CLAUDE.md, instructions you write. The other is auto memory, notes Claude writes itself from your corrections and preferences.

The docs advise adding to CLAUDE.md when Claude makes the same mistake twice, when a code review catches something it should have known, when you type the same correction you typed last session, or when a new teammate would need the same context.

Where the files live

The table above lists them from broadest to most specific. They load in that order, so a project instruction appears after a user instruction.

How loading works

Claude Code loads CLAUDE.md and CLAUDE.local.md from the current working directory and every directory above it. If you start Claude in foo/bar/, it loads foo/bar/CLAUDE.md and foo/CLAUDE.md. Files are concatenated, not overridden. Content runs from the filesystem root down to your working directory, so the file closest to you is read last. Within a directory, CLAUDE.local.md comes after CLAUDE.md.

Files in subdirectories below your working directory load on demand, once Claude reads, writes or edits a file in that subdirectory. This lets a large repository carry local rules without paying for them at startup.

For large projects the docs suggest splitting instructions into topic files under .claude/rules/, which can be scoped to certain file types. Rules with a paths: frontmatter load only when Claude touches matching files.

Imports

A CLAUDE.md can pull in other files with an @path import:

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

Paths can be relative to the importing file or absolute, and imports can chain up to four hops. Code spans and fenced code blocks are skipped, so wrapping a path in backticks mentions it without importing it. Imports do not reduce context cost, because imported files load together with the file that imports them. An import from outside your working directory, such as your home folder, triggers an approval dialog the first time, which protects you from files other people commit.

Writing good instructions

The docs' guidance is concrete:

• Be verifiable. "Use 2-space indentation" beats "format code properly." "Run npm test before committing" beats "test your changes." "API handlers live in src/api/handlers/" beats "keep files organised."
• Keep it short. Aim under 200 lines. Longer files use more context and reduce adherence.
• Structure it. Group related items under headers and bullets.
• Avoid contradictions. If two rules conflict, Claude may pick one arbitrarily. Review CLAUDE.md, nested files and rules from time to time.
• Move procedures out. A multi-step procedure, or a rule that matters only for one area, belongs in a skill or a path-scoped rule.

Run /init to generate a first version. Claude analyses the codebase and writes build commands, test instructions and conventions it finds; if a file exists, it suggests improvements. Then add what Claude could not discover by itself. A /doctor prompt-audit command checks your instruction files for outdated or conflicting content and proposes edits, without changing anything until you ask.

What it can and cannot do

CLAUDE.md is context. The docs say Claude treats it as context, not enforced configuration. That has practical effects:

• A rule may be followed 95 times out of 100. If a miss would be costly, use a hook or a permission setting.
• Instructions that are specific and short are followed more reliably.
• A rule given only in chat may vanish at compaction. Put important ones in the file.

After /compact, the project-root file is re-read from disk and re-injected. Nested files and path-scoped rules reload on demand. If an instruction disappeared after compaction, the docs list the likely causes: it was given only in conversation, it lives in a nested file that has not reloaded, or it is a scoped rule that has not matched a file yet.

CLAUDE.md and AGENTS.md

Claude Code can read an AGENTS.md instead of a CLAUDE.md. With an AGENTS.md and no CLAUDE.md, it reads AGENTS.md. With both, it reads CLAUDE.md only. The usual pattern for mixed teams is a CLAUDE.md that imports the shared file:

@AGENTS.md

Then add Claude-only lines below it. See AGENTS.md for the shared format and write a good CLAUDE.md for a longer guide.

A team workflow that works

Treat the project file like code. Put it in version control, change it in pull requests and let a review catch bad rules. When a reviewer says "Claude should have known that," the fix is one line in CLAUDE.md, not a longer chat prompt next time. Keep personal taste in CLAUDE.local.md so it never reaches teammates. Once a quarter, run the prompt audit and delete anything the model now does right without being told, because instructions written for older models can be dead weight. If your team also uses other coding agents, keep the shared rules in AGENTS.md and import them, so you maintain one source of truth.

Costs and context

Everything in CLAUDE.md is in every session, so it is a standing token cost. The context window explainer lists CLAUDE.md, auto memory, MCP tool names and skill descriptions among what loads before you type anything. A 300-line file costs more than a 100-line one on every turn. Trim lines that Claude would get right anyway, and move rarely-needed detail into skills. See the context window entry for why that adds up.

Do and do not

A tiny example

# Project notes
- Install: `pnpm install`. Test: `pnpm test`. Lint: `pnpm lint`.
- API handlers live in `src/api/handlers/`.
- Use 2-space indentation and named exports.
- Never edit files under `generated/`.
- Before finishing, run the tests and report failures.

Start from our CLAUDE.md starter template and adapt it.

Our take

CLAUDE.md is the cheapest way to make Claude Code fit a project: a short, accurate file beats repeating yourself every session. Its limit is that it is advice. Keep it small, update it when Claude repeats a mistake, and move anything long into a skill. We describe it from Claude Code's memory docs, checked on the date above, and the exact loading rules may change with versions. See Claude Code for the agent itself.