CLAUDE.md Done Right — Your Project's Constitution

Mastering Claude Code — Tips & Tricks Chapter: Level 1 (Fluent) › 1.1 CLAUDE.md Done Right The single highest-leverage tip in this entire guide.

If you only apply one chapter, apply this one. CLAUDE.md is the highest-leverage prompt you will ever write, because Claude Code loads it into every single session automatically — before you type anything. A good CLAUDE.md makes every future prompt smarter for free. A missing one makes Claude guess, and guessing is where the wrong package manager, the wrong test framework, and the "why did it rewrite my whole file" moments come from.

The One Idea

CLAUDE.md is a prompt that runs on every turn. Treat it like production code, not a scratch note.

Because it costs context tokens on every message, the goal is maximum signal per line: the handful of things Claude can't infer from the code but must always know.

What it actually is

When a session starts, Claude Code automatically pulls CLAUDE.md into context. You never have to say "remember to use pnpm" again — you write it once, and it's true for every prompt after. That's the whole magic: write once, apply always.

The memory hierarchy (where CLAUDE.md lives)

Claude Code reads several CLAUDE.md files and layers them together:

Parent-directory files also apply, so a monorepo can have a root constitution plus a small, focused CLAUDE.md in each package. The closer file wins for anything specific.

What to put in it (and what to leave out)

The best CLAUDE.md answers: "What would a sharp new engineer need pinned to their monitor on day one?"

✅ Put in:

• Commands — build, dev, test, lint, typecheck, single-test. The exact ones.
• Stack & versions — "pnpm (not npm/yarn)", "Vitest (not Jest)", "React 19".
• Conventions — file structure, naming, patterns you always follow.
• Architecture map — a 5-line orientation, or a link/import to a longer doc.
• "Never do X" rules — the hard constraints (see the dedicated section below).
• Environment quirks — "the dev server needs Docker up first", gotchas.

❌ Leave out:

• Anything Claude can read straight from the code (it will read the file itself).
• Giant dumps — a pasted-in full API spec bloats every turn's context.
• Secrets — ever. (See Chapter 2.6, Handling Credentials Safely.)
• Stale detail that will rot. If it changes weekly, don't hardcode it here.

Rule of thumb: if Claude can discover it by reading one obvious file, don't repeat it. If it would have to guess, write it down.

Before / After: the payoff demo

Same prompt — "add a test for the checkout total" — in two repos.

Without CLAUDE.md — Claude guesses your toolchain:

> add a test for the checkout total

Created checkout.test.js using Jest:
  import { describe, it, expect } from '@jest/globals'
  ...
$ npm test
✖  Cannot find module '@jest/globals' — this project uses Vitest, not Jest.
   Also: the project uses pnpm, not npm.

Wrong framework, wrong runner, wrong package manager. You spend the next five minutes correcting it — every time.

With a good CLAUDE.md containing:

## Commands
- Test: `pnpm test` (Vitest). Single file: `pnpm test <path>`
## Conventions
- Tests live next to source as `*.test.ts`, use `vitest` imports.

> add a test for the checkout total

Created src/checkout/total.test.ts:
  import { describe, it, expect } from 'vitest'
  ...
$ pnpm test src/checkout/total.test.ts
✓  total › applies tax and discount (3 ms)

First try. That five-minutes-saved, multiplied across every session, is why this chapter is #1.

The "Never do X" section is gold

The most valuable lines in any CLAUDE.md are the hard constraints — the things that, when Claude does them, cost you real time or real damage:

## IMPORTANT — Never do these
- NEVER commit directly to `main`. Always branch.
- NEVER run `prisma migrate reset` (it wipes the dev DB).
- NEVER add a dependency without asking — we keep the bundle small.
- ALWAYS run `pnpm typecheck` before saying a task is done.

Trick — emphasis works. Words like IMPORTANT, NEVER, and YOU MUST measurably improve adherence. Reserve them for the rules that actually matter, so they keep their weight.

Bootstrapping and maintaining it

You don't write CLAUDE.md from a blank page, and you don't write it once.

1. Generate a first draft — run /init. Claude analyzes the codebase and drafts a starting CLAUDE.md. Then trim it hard; the auto-draft is a start, not the finish.
2. Grow it from friction — every time Claude gets something wrong the same way twice, that's a missing line. Add the rule; you've just permanently fixed it.
3. Add memories on the fly — start a line with # in the prompt to quickly save a note into CLAUDE.md without leaving your flow. Use /memory to open and edit the files directly.
4. Prune ruthlessly — a bloated CLAUDE.md is a worse prompt. If a line no longer earns its token cost, delete it.

Mindset: CLAUDE.md is a living prompt you tune, exactly like you'd tune any other prompt — iterate toward the version that makes Claude right the first time.

Keep it modular with imports

For anything long, don't inline it — import it so the root file stays lean:

See @docs/architecture.md for the full system map.
Coding standards: @docs/conventions.md

Claude pulls imported files in when relevant. This keeps your root CLAUDE.md short and scannable while still giving Claude the depth when it needs it. (Keep imports shallow — a few hops, not a maze.)

Path-scoped rules: .claude/rules/

For bigger projects, official guidance now recommends splitting standing rules into separate .claude/rules/*.md files. Each file can carry YAML frontmatter like paths: ["src/api/**/*.ts"], so the rule loads only when Claude works on matching files — your API rules don't tax a frontend session. That keeps the root CLAUDE.md tiny while your rulebook scales across a monorepo. See the memory docs.

The caveat

More is not better. A 400-line CLAUDE.md that repeats what's already in the code makes every prompt slower and dilutes the rules that matter. Official best practices suggest keeping each CLAUDE.md to a couple hundred lines at most — for every line, ask "would removing this cause mistakes?" The best CLAUDE.md is short, sharp, and mostly "never do X" + "here are the commands." Signal, not volume.

Downloadable: the CLAUDE.md Template Pack

Ready to drop into any project, in ../artifacts/claude-md-template-pack/:

Install in one line:

cp CLAUDE.md.template /path/to/your/project/CLAUDE.md

Then delete the sections you don't need, fill in your commands, and add your first three "never do X" rules. That's a professional CLAUDE.md in five minutes.