CLAUDE.md: how to write one that actually works

Every Claude Code session starts with an empty context window. It does not remember that your tests run with pnpm test:unit, that you banned default exports, or that the legacy/ folder is off limits. CLAUDE.md is where you write that down once so you stop retyping it.

What belongs in it#

Treat it as the page you would hand a new teammate on day one. Add a line when:

• the agent makes the same mistake a second time,
• a code review catches something it should have known about this repo,
• you type the same correction into chat that you typed yesterday.

Good content is facts that hold in every session: build, test and lint commands, project layout, naming conventions, and "always do X" or "never do Y" rules.

Where the file lives#

Files in parent directories load at launch; files in subdirectories load on demand when the agent works there. Run /context in a session to confirm your file loaded.

Start with /init#

Run /init in your repo. Claude analyzes the codebase and writes a first CLAUDE.md with the build commands, test instructions and conventions it finds. If one exists, it suggests improvements instead of overwriting. Then edit it: delete what the agent could work out itself and add what it could not.

Write rules it can verify#

Vague rules get ignored. Concrete ones get followed.

A template that stays short#

# Project: invoice-api

## Commands
- Install: `pnpm install`
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Lint + types (run before every commit): `pnpm lint && pnpm tsc --noEmit`

## Layout
- `src/api/handlers/` HTTP handlers, one file per route
- `src/domain/` pure business logic, no I/O
- `src/db/` queries; never import from here in `domain/`

## Conventions
- TypeScript strict, no `any`. Use `unknown` and narrow.
- Named exports only.
- Errors: throw `AppError` subclasses, never strings.

## Don't
- Don't edit files in `generated/`.
- Don't add dependencies without asking.

Import instead of copy#

CLAUDE.md can pull in other files with @path syntax:

See @README.md for the overview and @package.json for npm scripts.
- Git workflow: @docs/git-instructions.md

Imports load at launch, so they organize a long file but do not reduce its context cost. For rules that only matter in one area, use path-scoped rules in .claude/rules/ or a skill so they load only when relevant.

If you already have AGENTS.md#

Claude Code can read a repo's AGENTS.md in place of CLAUDE.md. To keep one source of truth, make CLAUDE.md a thin file that imports it:

@AGENTS.md

## Claude Code only
- Use plan mode for changes that touch more than three files.

Mistakes that make it worse#

• Too long. Past roughly 200 lines, adherence drops and you pay for the tokens every session.
• Contradictions. Two rules that disagree get resolved arbitrarily. Review it now and then; /doctor prompt-audit can find outdated and conflicting instructions.
• Style essays. "Write clean, maintainable code" does nothing. Delete it.
• Treating it as enforcement. It is context. For must-never-happen rules, use a hook.
• Secrets. It is committed to git. Never put keys in it.

Quick checklist#

1. Run /init, then cut it down.
2. Every line is checkable by a test, a command or a glance.
3. Under about 200 lines.
4. Personal stuff in ~/.claude/CLAUDE.md or CLAUDE.local.md.
5. Review it whenever the agent repeats a mistake.

Related: what is Claude Code and context engineering. Official reference: How Claude remembers your project.