CLAUDE.md: What to Put in It and What to Leave Out

CLAUDE.md is a Markdown file of instructions that Claude Code reads at the start of every session, so the commands, conventions and rules you would otherwise repeat are already in context (Claude Code docs: memory). Keep one in the project for shared rules and one in ~/.claude/ for personal ones, hold each under about 200 lines, and leave out what Claude can read from the code or must never skip, because Claude treats the file as context, not enforced configuration. Every claim below was checked against the docs on October 3, 2026.

Where does Claude Code look for CLAUDE.md?

In four scopes, loaded from broadest to most specific, so a project instruction appears in context after a user instruction (where to put CLAUDE.md):

At launch Claude Code loads CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it; a CLAUDE.md in a subdirectory loads later, when Claude reads files there (how CLAUDE.md files load). Files are concatenated rather than overriding each other, from the filesystem root down, with CLAUDE.local.md after CLAUDE.md at each level. If two files disagree, Claude may pick one arbitrarily. To see what loaded, run /context and check the list under Memory files.

How do @ imports work?

A CLAUDE.md can pull in another file with @path/to/import, and the imported file is expanded into context at launch alongside the file that references it (import additional files). Relative paths resolve from the file that contains the import, not from the working directory, and imports can nest up to four hops deep. A path wrapped in backticks stays literal, which is how you mention a file without loading it. The first time a project file imports something outside the working directory, Claude Code shows an approval dialog; imports in your own ~/.claude/CLAUDE.md load without it, except in desktop Cowork sessions, which skip the external ones.

See @README for project overview and @package.json for available npm commands for this project.
 
# Additional Instructions
- git workflow @docs/git-instructions.md

Imports organize a long file but do not shrink it: imported files load at launch too.

What should go in CLAUDE.md?

Facts Claude should hold in every session: build commands, conventions, project layout and "always do X" rules (when to add to CLAUDE.md). Add a line when Claude makes the same mistake a second time, when a code review catches something Claude should have known, or when you type a correction you already typed last session. The best practices page adds Bash commands Claude can't guess, code style rules that differ from defaults, testing instructions, repository etiquette, project-specific architectural decisions, environment quirks and common gotchas (write an effective CLAUDE.md). Write each rule concrete enough to verify: "Use 2-space indentation", not "Format code properly".

What should you leave out?

The same page lists anything Claude can figure out by reading code, standard conventions it already knows, detailed API documentation (link to it instead), information that changes often, long tutorials, file-by-file descriptions of the codebase, and advice like "write clean code". Its test for every line is whether removing it would cause Claude to make mistakes; if not, cut it, since the docs target under 200 lines per file and say longer files consume more context and reduce adherence (write effective instructions).

Two kinds of content belong elsewhere. A multi-step procedure becomes a skill, which loads only when you invoke it or Claude finds it relevant, and an instruction for one part of the codebase becomes a file in .claude/rules/ with a paths field, which loads only when Claude works on matching files (path-specific rules). If one line keeps getting skipped, the best practices page suggests "IMPORTANT" on that line alone; emphasize many and none stands out. Where a rule belongs among CLAUDE.md, a skill and a hook is laid out in my post on skills.

Does Claude always follow CLAUDE.md?

No. Claude treats CLAUDE.md as context, not enforced configuration, and the content is delivered as a user message after the system prompt, not as part of it, so there is no guarantee of strict compliance (troubleshoot memory issues). The docs send anything that must run at a fixed point, such as after each file edit, to a hook, and anything that must be blocked regardless of what Claude decides to a PreToolUse hook. Settings such as permissions.deny are enforced by the client; CLAUDE.md shapes behavior but is "not a hard enforcement layer" (managed CLAUDE.md).

How do you create and check a CLAUDE.md?

Run /init: Claude analyzes the codebase and writes a starter file with the build commands, test instructions and conventions it finds, or suggests improvements to an existing one (set up a project CLAUDE.md). Then add what Claude wouldn't discover on its own. /memory lists your CLAUDE.md files, including ones that don't exist yet, and opens or creates the one you pick. On v2.1.283 or later, /doctor prompt-audit reports instructions written for older models, references to files or commands that don't exist, and files that contradict each other, and changes nothing until you ask (audit your instruction files).

How do I split a personal and a project CLAUDE.md?

My personal ~/.claude/CLAUDE.md holds the working rules that follow me into every project: the language I talk in, never commit or push without my explicit approval, and no AI attribution in commits. The project CLAUDE.md holds what only this site needs: positioning and copy rules, such as what the site sells and which words never appear in its copy. Its first line is @AGENTS.md.

That line works around a default: when a project has both files, Claude Code reads only the CLAUDE.md files unless CLAUDE.md imports AGENTS.md, and keeping the import never makes Claude read AGENTS.md twice (AGENTS.md). AGENTS.md is "a README for agents" that other coding tools read too (agents.md), so the import keeps one shared file instead of two copies.

What goes in auto memory instead?

Notes Claude writes for itself. Mine is a memory folder with one fact per file and a MEMORY.md index, and its saved rules include: run the dev server on port 3100, never 3000; check consent from a non-EU location; write manuals without filler. The docs draw the same line: you write CLAUDE.md, Claude writes auto memory, and only the first 200 lines or 25KB of MEMORY.md load each session (auto memory).

Which rules should not rely on CLAUDE.md alone?

The ones a machine can check. Copy rules that a script can test also live in scripts/content_lint.py, which fails the run on em dashes, links to removed or missing pages, over-long titles and descriptions, and banned phrasing. The git rules are a request in my personal file, and I approve every commit and push myself. The settings that would back them exist: attribution set to false hides commit and pull request attribution from v2.1.281 on, while earlier versions skip the whole settings file that holds it (attribution), and an entry in permissions.ask such as Bash(git push *) prompts before a push, though a push written another way, such as git -C . push, isn't matched (permissions). Per the settings page, Claude is told that a CLAUDE.md rule about attribution takes precedence over its default commit and PR lines. In ~/.claude/settings.json they would look like this:

{
  "attribution": false,
  "permissions": {
    "ask": ["Bash(git push *)"]
  }
}

Where enforcement starts

CLAUDE.md tells Claude what you expect; it cannot make a rule hold. When a rule must hold on every edit, it belongs in a script that fails and a hook that runs it, which is how I set up Claude Code hooks to enforce the rules agents forget.