CLAUDE.md template — a copy-paste starter, plus where each file actually goes

A CLAUDE.md is the file Claude Code reads at the start of every session to learn your project — build commands, conventions, the things it would otherwise get wrong twice. This page is a copy-paste starter, plus the part most guides skip: which file to put what in, because Claude Code loads several CLAUDE.md files at once and they’re not interchangeable. (For the writing craft once you have the file, see how to write a great CLAUDE.md; for the cross-tool AGENTS.md question, start here.)

The project template

Drop this at your repo root as CLAUDE.md (or .claude/CLAUDE.md), fill in your stack, delete what doesn’t apply:

# CLAUDE.md

## Project
One paragraph: what this is, the stack, and the one architectural fact
Claude keeps getting wrong. (e.g. "API and worker share types from
packages/core — change them together or the build breaks.")

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test one file: `pnpm vitest run <path>`   # not the whole suite
- Lint + typecheck: `pnpm lint && pnpm tsc --noEmit`
- Never run: `pnpm deploy` (CI only), `pnpm db:reset` (destructive)

## Conventions
- TypeScript strict. No `any` — fix the type, don't cast around it.
- Imports absolute from `src/`. No deep `../../` chains.
- Errors: throw typed `AppError` subclasses, never bare strings.
- Match the nearest existing file's patterns for new code.

## Boundaries
- Don't edit `src/generated/**` — regenerated on build.
- Append new files in `db/migrations/`; never edit existing ones.
- Secrets come from env vars. Never hardcode or commit real data.

## Done means
- `pnpm test` green, no new lint/type errors.
- Behavior change ⇒ a test changed or added.

<!-- maintainer note: keep this under 200 lines; move topic detail to .claude/rules/ -->

That last line is a real trick, not decoration: block-level HTML comments are stripped before the file enters Claude’s context, so you can leave notes for human maintainers without spending a single token on them.

Where each file goes (the part that matters)

Claude Code loads CLAUDE.md from several scopes, broadest to most specific, and concatenates them — they don’t override each other. Put each instruction where its audience is:

The single most common mistake is putting personal preferences in the shared project file — that ships your habits to every teammate and quietly burns tokens for all of them. The fix is the scope table above: shared facts in the project file, your taste in your user file.

The personal companion

Your ~/.claude/CLAUDE.md applies to every project on your machine. Keep it to genuine cross-project preferences:

# ~/.claude/CLAUDE.md

- Explain non-obvious changes in one line before the diff.
- Prefer standard library over adding a dependency; ask before adding one.
- When tests fail, show me the failing output before proposing a fix.
- Commit messages: imperative mood, no "Generated by" footers.

If a rule is true only for one repo, it belongs in that repo’s file — not here.

One source of truth: imports and the AGENTS.md bridge

CLAUDE.md can pull in other files with @path syntax, expanded into context at launch (relative or absolute paths, @~/ home paths work, up to four hops deep):

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

This is also how you avoid maintaining two instruction files if your repo already has an AGENTS.md. Claude Code doesn’t read AGENTS.md natively — the docs say so verbatim: “Claude Code reads CLAUDE.md, not AGENTS.md.” So make CLAUDE.md a one-line shim that imports it:

@AGENTS.md

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

Every tool reads AGENTS.md; Claude reads it plus your Claude-only lines. (Full setup, including the symlink alternative and the monorepo layout, is in the AGENTS.md template.)

Two commands worth knowing

• /init generates a starting CLAUDE.md by analyzing your codebase — build commands, test instructions, conventions it discovers. If one already exists, it suggests improvements instead of overwriting. It also absorbs an existing AGENTS.md, .cursorrules, .devin/rules/, and .windsurfrules. Best used as a first draft you then trim.
• /memory lists every CLAUDE.md and CLAUDE.local.md actually loaded in the current session and opens any of them for editing. If an instruction isn’t being followed, run /memory first — if the file isn’t listed, Claude can’t see it.

Keep it lean

CLAUDE.md loads in full on every session, so size is a recurring tax on tokens and attention — target under 200 lines. When a project outgrows that, don’t cram: split topic detail into .claude/rules/ files (which can be path-scoped to load only when Claude touches matching files). The discipline is the same one that makes the template above short: every line should be something Claude would otherwise get wrong, not something it already knows.

Companion reading

• AGENTS.md template — the cross-tool counterpart, for repos with more than one agent.
• How to write a great CLAUDE.md — the craft, with real before/after rewrites.
• CLAUDE.md vs AGENTS.md — which file Claude Code actually reads, and the bridge.
• Five habits that quietly burn tokens — what to keep out of the file.