How to Write a CLAUDE.md That Claude Actually Follows

The documentation gives a simple trigger for adding a line: Claude makes the same mistake a second time, a code review catches something Claude should have known, you type the same correction you typed last session, or a new teammate would need the same context.

And a simple test for keeping one: for each line, ask "Would removing this cause Claude to make mistakes?" If not, cut it. Directory layouts, dependency lists, and architecture overviews usually fail that test, because Claude can read them from the code; the /doctor checkup proposes exactly those cuts for a checked-in CLAUDE.md, while keeping pitfalls, rationale, and conventions that differ from tool defaults.

A starting file can be generated: /init analyses the codebase and writes build commands, test instructions, and conventions it finds, or suggests improvements if a CLAUDE.md already exists. Treat its output as a draft and delete what Claude would have discovered anyway.

Because CLAUDE.md is advisory, phrasing matters. The documentation's guidance is to write instructions concrete enough to verify: "Use 2-space indentation" rather than "Format code properly", "Run npm test before committing" rather than "Test your changes", "API handlers live in src/api/handlers/" rather than "Keep files organized".

Here is a typical first draft and a rewrite:

1# Before2- Write clean, well-tested code3- Follow our coding standards4- Be careful with the database5- The project uses React and TypeScript

1# Commands2- Typecheck: `npm run typecheck`; run it after a series of edits3- Single test file: `npm test -- path/to/file.test.ts` (the full suite takes minutes)4 5# Conventions6- Named exports only; no default exports in `src/`7- Dates are stored as UTC ISO strings; convert only in the UI layer8 9# Gotchas10- Never edit files in `migrations/` by hand; generate them with `npm run db:migration`11- `.env.example` must list every new environment variable

Each line in the rewrite is one action Claude can take or a fact it can check, and the vague lines are gone: "write clean code" adds nothing, and "uses React and TypeScript" is visible from package.json.

Structure helps too: group related instructions under headers and bullets rather than paragraphs. If one rule keeps being skipped, the documentation suggests emphasis such as "IMPORTANT" on that line alone; emphasise many lines and none stands out.

CLAUDE.md files can live at four scopes, loaded from broadest to most specific:

• Managed policy: an organisation-wide file installed by IT (for example /etc/claude-code/CLAUDE.md on Linux).
• User: ~/.claude/CLAUDE.md, your preferences across all projects.
• Project: ./CLAUDE.md or ./.claude/CLAUDE.md, shared through version control.
• Local: ./CLAUDE.local.md, your personal notes for this project; add it to .gitignore.

Claude Code loads CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it at launch. The files are concatenated, not overridden: content runs from the filesystem root down to your working directory, and within each directory the local file comes after CLAUDE.md. Files in subdirectories load on demand, when Claude reads, writes, or edits a file in that subdirectory.

Two consequences matter in practice. First, a contradiction between files is not resolved by precedence: the documentation warns that Claude may pick one arbitrarily, so remove conflicts rather than relying on the more specific file to win. Second, the project-root CLAUDE.md survives /compact, because Claude re-reads it from disk; instructions given only in conversation do not, so anything you want to persist belongs in the file.

Block-level HTML comments (<!-- note for maintainers -->) are stripped before the content reaches Claude, so you can leave notes for humans at no context cost.

Imports pull other files into a CLAUDE.md with @path syntax. Relative paths resolve from the file that contains the import, imports can nest up to four hops, and the first time a project imports a file from outside the working directory Claude Code asks you to approve it. Imports help organise a long file but do not reduce its context cost: imported files load at launch too.

1See @README.md for the project overview and @package.json for npm scripts.2 3# Git workflow4- @docs/git-instructions.md

Wrap a path in backticks to mention it without importing it.

Path-scoped rules are the tool that does reduce cost. Put a markdown file in .claude/rules/ with paths frontmatter, and it loads only when Claude works with a matching file:

1---2paths:3  - "src/api/**/*.ts"4---5 6# API rules7- Validate every request body with the shared Zod schemas in `src/api/schemas/`8- Return errors in the `{ error: { code, message } }` shape

Rules without paths load at launch like the project CLAUDE.md. paths is the only frontmatter field rules read.

Move content out of CLAUDE.md when it matches one of these patterns: it applies to one area of the code (path-scoped rule), it is a procedure or domain knowledge needed only sometimes (a skill, which loads when relevant), or it must happen every time without exception (a hook).

Many repositories already have an AGENTS.md for other coding agents. Recent Claude Code versions read it directly, with a simple default:

• An AGENTS.md and no CLAUDE.md or CLAUDE.local.md in your working directory or above: Claude reads the AGENTS.md.
• An AGENTS.md and a project CLAUDE.md or CLAUDE.local.md: Claude reads only the CLAUDE.md files.
• A CLAUDE.md that imports AGENTS.md: Claude reads both, through the import.

Your ~/.claude/CLAUDE.md, the managed file, and .claude/rules/ don't count for that check and load alongside AGENTS.md. The Project instructions setting in /config changes the default, for example to read both.

The trap is CLAUDE.local.md: creating one for personal notes in an AGENTS.md-based repository stops Claude from reading the AGENTS.md. The portable pattern for teams that use several tools is one shared file plus a thin CLAUDE.md:

1@AGENTS.md2 3# Claude Code only4- Use plan mode for changes under `infra/`

When Claude doesn't follow a line, work through the causes in order:

1. Did the file load? Run /context and look under Memory files. A subdirectory CLAUDE.md won't appear there because it loads on demand; a Loaded line appears in the terminal when it does. The InstructionsLoaded hook can log which files and rules load, and why. 2. Is the line specific? Rewrite it as a single checkable action. 3. Does something contradict it? Check other CLAUDE.md files, .claude/rules/, and Claude Code's own built-in guidance: if your file sets commit or pull request rules, the documentation suggests turning off the built-in ones with includeGitInstructions and setting attribution. 4. Is the file too long? Over about 200 lines, rules get lost; Claude Code warns at startup when a file, or the combined set, is too large. /doctor prompt-audit (in recent versions) reports outdated, missing-file, and contradictory instructions and proposes edits without changing anything until you ask. 5. Must it always happen? Then CLAUDE.md is the wrong tool. Write a hook: hooks run as commands at fixed lifecycle events, regardless of what Claude decides. To block an action outright, use a PreToolUse hook.

Test changes the way you would test code: start a fresh session, give a task that should trigger the instruction, and see whether behaviour changes.

Use a repository you work in daily.

1. Run /context and record which memory files load and how long each is. 2. Apply the removal test to every line of the project CLAUDE.md. Delete what fails; move area-specific lines to a .claude/rules/ file with paths, and procedures to a skill. 3. Rewrite each remaining vague line as one checkable action or fact. 4. Pick two instructions Claude previously ignored. Start a fresh session and give a task that should trigger each. 5. For any instruction that must always hold (a forbidden directory, a required check), write a hook instead and delete the line.

Pass criterion: the project CLAUDE.md is under 200 lines, every line passes the removal test, and both previously ignored instructions are now followed or enforced by a hook.