CLAUDE.md Best Practices: The Exact Template to Give Every New Project

CLAUDE.md is the file Claude Code reads at the start of every session — the onboarding document for an engineer who joins your project fresh each morning with no memory of yesterday. Everyone knows it matters. Almost nobody knows what to actually put in it, which is why most CLAUDE.md files are either three unhelpful lines or 800 lines of wishful thinking that Claude skims and forgets. This guide gives you the principles and the exact template.

The one rule that governs everything: this file costs context

Every line of CLAUDE.md is loaded into every session, whether relevant or not. That means two failure modes:

• Too short, and Claude re-derives your stack, guesses your conventions, and repeats mistakes you've already corrected ten times.
• Too long, and the instructions compete with each other for attention. A 900-line CLAUDE.md doesn't give you 900 lines of obedience — it gives you a model that weighs your genuinely critical rule the same as your note about import ordering.

The sweet spot for most projects is under ~200 lines. The test for every line: would a competent new hire need to be told this, and does it apply to most sessions? If it only applies to some tasks, it belongs in a skill that loads on demand. If it's discoverable from the code in seconds, delete it.

The template

# <Project name>

<One sentence: what this project is and who uses it.>
Stack: <framework + language + DB + anything unusual>.

## Commands
- <dev server command> — <port / notes>
- <test command> — run before claiming any change works
- <lint / typecheck command>
- <build or deploy command, if Claude may run it>

## Architecture
- <2–6 bullets: the main directories and what owns what>
- <where the "front door" is: entry points, routing>
- <the one data-flow fact that isn't obvious from the tree>

## Conventions
- <how code is organized: e.g. "all DB access via src/db/queries/">
- <error handling rule>
- <naming or style rule that lint doesn't enforce>
- <what to do about types: e.g. "no any — fix the type">

## Workflow
- <branching / commit rules, e.g. "commit as you go, small diffs">
- <verification rule: "run tests + typecheck before done">
- <what Claude must NOT do without asking: migrations,
  deleting data, touching payments code>

## Gotchas
- <the 2–5 landmines every new engineer steps on>

That's the whole structure: identity, commands, architecture, conventions, workflow, gotchas. Run /init to draft the mechanical parts from your codebase, then spend your effort on the last three sections — they're the parts Claude can't figure out by reading the code.

What earns a line (and what doesn't)

Put in: things Claude gets wrong without being told

• Commands with their quirks. Not just npm test but "tests need the DB container running: docker compose up -d db first."
• Non-obvious boundaries. "The legacy/ folder is frozen — bugfix only, never refactor."
• Verification expectations. "A change isn't done until typecheck and tests pass" changes Claude's behavior more than any style rule.
• Corrections you've made twice. This is the highest-signal source. The second time you correct the same mistake in chat, move the correction into the file.

Leave out: everything Claude can see or doesn't need

• Directory listings and file inventories — Claude can list files. Explain meaning, not contents.
• Anything your linter or formatter already enforces. Tools beat instructions; if prettier fixes it, don't spend attention on it.
• Long task-specific procedures (release process, migration recipes). Those belong in skills, loaded only when relevant.
• Aspirational essays about code quality. "Write clean, maintainable code" has never changed a model's behavior. Specific, checkable rules do.

Three habits that keep it working

1. Treat it as a living file. The best CLAUDE.md files are grown, not written — every corrected mistake is a candidate line. In-session, the # shortcut appends a memory to the file without breaking flow.
2. Prune on a schedule. Rules outlive their reasons. When you touch the file, delete lines about code that no longer exists — every dead line dilutes attention paid to live ones.
3. Review it in PRs like code. Project-level CLAUDE.md is shared team configuration checked into git. A bad instruction misleads every teammate's sessions, which makes it exactly as review-worthy as a bad function.

Layering: project, subdirectory, user

Claude Code merges CLAUDE.md files from several levels: ~/.claude/CLAUDE.md for your personal preferences across all projects, the repo root for team-shared rules, and subdirectory CLAUDE.md files for area-specific guidance (a frontend/CLAUDE.md with component conventions, an infra/CLAUDE.md with deployment cautions). Subdirectory files are pulled in when Claude works in those directories — a clean way to keep the root file lean on a large codebase.

FAQ

Keep reading