CLAUDE.md Template: A Copy-Paste Starter (and 7 Rules for Writing a Good One)

Published Oct 15, 2026 · 6 min read

CLAUDE.md is Claude Code's project memory. It's loaded into every session, so every line costs context every turn. Most CLAUDE.md files fail in one of two ways: they're empty, or they're a 600-line wiki dump that Claude skims. Here's a template that avoids both.

The template

# Project: <name>
<One sentence: what this is and who uses it.>

## Commands
- Install: `<npm install>`
- Dev: `<npm run dev>`
- Test: `<npm test>`  (single file: `<npm test -- path>`)
- Lint/format: `<npm run lint>`
- Typecheck: `<npm run typecheck>`

## Layout
- `src/<area>/`: <what lives here>
- `tests/`: mirrors src/

## Conventions
- <Language/strictness rule, e.g. strict TS, no any>
- <Architecture rule, e.g. no DB calls from components>
- <Naming/file rule>

## Definition of done
1. Tests and typecheck pass
2. New behavior has a test
3. Diff reviewed (use the code-reviewer subagent)

## Guardrails
- Never edit .env*, lockfiles, or migrations already applied
- Never add a dependency without asking
- If requirements are ambiguous, ask ONE question instead of guessing

7 rules for a CLAUDE.md that works

1. Commands first. The highest-value lines are the exact test, lint and build commands. Claude guesses wrong without them.
2. Facts, not procedures. Multi-step workflows such as deploys or releases belong in a skill (.claude/skills/<name>/SKILL.md), which loads only when used.
3. Keep it short. Under about 150 lines. If Claude can work it out from the code, delete it.
4. Be specific. "Use zod at API boundaries" beats "validate input."
5. Write a definition of done. This alone kills most "it compiles, ship it" behavior.
6. Enforce must-never rules with hooks. CLAUDE.md is guidance. A hook is a guarantee. See Claude Code hooks examples.
7. Nest for monorepos. Put shared rules at the root and app-specific rules in apps/web/CLAUDE.md. Claude loads nested files when it works in those folders.

Where CLAUDE.md files live

• ./CLAUDE.md: project, committed for the team
• ~/.claude/CLAUDE.md: your personal defaults for every project
• Subfolder CLAUDE.md: loaded when Claude works in that folder

Run /init in a repo to have Claude draft one, then cut it down using the rules above. Use /memory to open and edit it.