CLAUDE.md: How to Write One Claude Actually Follows

CLAUDE.md is the file where you tell Claude Code how your project works: which commands to run, what conventions to follow and what never to touch. Claude reads it at the start of every session.

Write it well and you stop repeating yourself. Write it badly and Claude follows it about as reliably as a new hire skims a wiki.

I think about CLAUDE.md the same way I think about the brains I build in Obsidian. A rule that only lives in prose is a suggestion. The goal is a short file of specific, checkable instructions, backed by hooks for anything that can't be left to judgment.

What is CLAUDE.md?#

Every Claude Code session starts with an empty context window. Two mechanisms carry knowledge between sessions, according to Anthropic's memory documentation:

Both are context, not configuration. Claude reads them and tries to follow them, but nothing forces it to. That distinction shapes everything about how you should write the file.

Where does the CLAUDE.md file go?#

There are four levels, loaded from broadest to most specific:

Two loading rules trip people up. First, files are combined, not overridden: Claude Code loads the CLAUDE.md in your working directory and every folder above it, and the instructions closest to where you started are read last. Second, CLAUDE.md files in subfolders load on demand, only when Claude reads files in those folders.

To check what actually loaded, run /context and look under Memory files.

What should you put in CLAUDE.md?#

Add to it whenever one of these happens:

• Claude makes the same mistake twice
• A code review catches something Claude should have known about this codebase
• You type the same correction you typed last session
• A new teammate would need the same context to be productive

Keep it to facts that matter in every session: build and test commands, conventions that differ from defaults, where things live, and hard "always" and "never" rules. If something is a multi-step procedure or only applies to one area of the code, it belongs in a skill or a path-scoped rule instead.

What to leave out: anything Claude can work out by reading the code, such as a full directory tree or a dependency list. Anthropic's /doctor check will even propose trimming exactly that kind of content.

How do you write instructions Claude follows?#

Stay under 200 lines. Anthropic's guidance is explicit that longer files use more context and reduce adherence. The cost documentation makes the same point from the billing side, since the whole file is sent with every session.

Make each rule verifiable. Compare:

• "Format code properly" versus "Use 2-space indentation"
• "Test your changes" versus "Run npm test before committing"
• "Keep files organized" versus "API handlers live in src/api/handlers/"

Write imperatives, not observations. "Never use inline mocks; use src/test/factories" works better than "we generally avoid inline mocks."

Use headings and bullets. Claude scans structure the way a person does.

Remove contradictions. If two files disagree, Claude may pick either one. Review your CLAUDE.md files when the project changes.

A CLAUDE.md template you can copy#

# Project: Acme dashboard
 
## Commands
- Install: `pnpm install` (never npm or yarn)
- Dev server: `pnpm dev` on port 3000
- Tests: `pnpm test` must pass before any commit
- Type check: `pnpm typecheck`
 
## Conventions
- TypeScript strict mode; no `any`
- Server components by default; add "use client" only when needed
- Database access only through `src/lib/db.ts`
 
## Structure
- Routes: `src/app/`
- Shared UI: `src/components/ui/`
- Business logic: `src/lib/`
 
## Rules
- Never edit files in `src/generated/`; regenerate with `pnpm codegen`
- Never commit `.env` files
- Ask before adding a new dependency
 
## Workflow
- Use plan mode for changes touching more than three files
- Keep pull requests small; one concern per branch

That's around 25 lines. Most good project files stay under 80.

How to organize a bigger setup#

When one file gets crowded, you have three tools:

1. Imports. Write @docs/git-workflow.md to pull another file in. Paths resolve relative to the file doing the importing, imports can nest up to four levels, and imported files still load at startup, so they help organization rather than context size.
2. Path-scoped rules. Put focused files in .claude/rules/ with a paths list in their frontmatter, such as src/api/**/*.ts. They load only when Claude works on matching files.
3. Skills. Move long procedures, like a release checklist, into a skill that loads only when the task calls for it. My guide to Claude skills explains how.

Two small extras: HTML comments in CLAUDE.md are stripped before Claude sees them, so you can leave notes for humans for free, and the project-root file is re-read after /compact, so it survives long sessions.

CLAUDE.md vs AGENTS.md#

Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already has an AGENTS.md for Codex or other agents, don't duplicate it. Create a CLAUDE.md like this:

@AGENTS.md
 
## Claude Code
Use plan mode for changes under `src/billing/`.

Claude loads AGENTS.md first and then your Claude-specific additions. It's the setup I recommend when a team runs both agents, which I cover in Claude Code vs Codex.

When CLAUDE.md isn't enough: use hooks#

Because CLAUDE.md is context, "always run the tests before committing" will be followed most of the time, not every time. When a rule must hold every time, write it as a hook: a shell command Claude Code runs at a fixed lifecycle event, such as before a tool runs or after a file is edited, whatever the model decides.

That's the same principle behind the evidence linter in my brains: prose describes the rule, code enforces it. If you'd like that kind of system built around your own project knowledge, see the AI Brains. If you're just getting started, pair this guide with how to use Claude Code.