Guides

CLAUDE.md: a template and what actually belongs in it

CLAUDE.md is loaded into every Claude Code session in your repository. Everything in it costs context on every task, so the best CLAUDE.md files are short, specific, and full of things Claude couldn't figure out alone.

Where CLAUDE.md files live

• ./CLAUDE.md in the repo root, shared with your team through git.
• CLAUDE.md files in subdirectories, used when Claude works in that part of the tree. They're great for monorepos.
• ~/.claude/CLAUDE.md holds your personal preferences for every project.
• CLAUDE.local.md holds private notes for one project. Add it to .gitignore.

Pull in longer docs with an import line, for example @docs/architecture.md, instead of pasting them.

What belongs in it

1. Commands that are copy-pasteable and verified: dev server, single-test invocation, lint, typecheck, migrations. This is the highest-value section.
2. A definition of done, for example: "Before saying a task is done: typecheck, lint and relevant tests must pass."
3. Layout: where things live, and which directories are generated and must not be edited.
4. Conventions Claude would otherwise get wrong: the error-handling pattern, the data-fetching approach, the test style.
5. Landmines: "The webhook route must read the raw body", or "Jobs can be delivered twice, so keep them idempotent".

What to leave out

• Generic advice like "write clean code" or "follow best practices". It costs context and changes nothing.
• Anything a linter or formatter already enforces.
• Long API docs, which belong behind an @import or in a skill.
• Secrets. CLAUDE.md is committed to your repository.

Copy-paste template

# <Project name>

<One sentence: what this does and who uses it.>

## Stack
<Language/framework/versions> · <DB> · <hosting>

## Commands
- Dev: `<cmd>`
- Test one file: `<cmd path/to/test>`
- All tests: `<cmd>`
- Lint / types: `<cmd>` / `<cmd>`
Before saying a task is done: types, lint and relevant tests must pass.

## Layout
- `src/...`: <what>
- `<generated dir>`: generated, never edit by hand

## Conventions
- <Error handling pattern>
- <Validation at boundaries with X>
- <Test style: real DB via fixtures, no ORM mocks>

## Don't
- Don't add dependencies without asking.
- Don't silence type errors with any / @ts-ignore.

## Landmines
- <The thing that bit someone last month>

Keep it alive

When Claude makes the same mistake twice, add one line to CLAUDE.md that prevents it. Delete lines that no longer apply. A 60-line file that's all signal beats a 400-line one that's mostly noise.