CLAUDE.md That Actually Works

The Problem

Every new Claude Code session starts cold. Without persistent context, you spend the first few minutes re-explaining your stack, your test runner, your branch conventions, and your anti-patterns. Then you correct the same avoidable mistakes again and again — in every session.

What to Include

CLAUDE.md isn't a tutorial. It's a cheat sheet for an engineer who already knows how to code. Include only what the agent can't infer from reading the code itself:

• Run commands: how to start the dev server, run tests, type-check
• Stack conventions: ES modules vs CommonJS, import aliases, preferred patterns
• Branch and PR rules: naming conventions, when to open a PR vs direct commit
• Known gotchas: required env vars, ports, quirks in your monorepo setup
• Anti-patterns: "never use X, use Y instead" — this is the highest-ROI line you can write

What to Cut

If Claude already follows a convention without being told, cut it. Bloated files cause the agent to skim — and the important rules get lost in the noise.

• Don't explain standard conventions the model already knows
• Don't paste in API docs — link to them
• Don't write "follow best practices" or "write clean code" — these are noise
• If removing a line wouldn't cause a mistake, remove it

Start with /init

Claude Code's /init command generates a starter CLAUDE.md by analyzing your project structure. Use it as a base, then trim aggressively. The goal is the shortest file that still prevents real mistakes.

Example

1# Stack
2
3- React Router v7, TypeScript, Tailwind CSS
4- Node >= 24.0.0
5
6# Commands
7
8- `npm run dev` — start dev server on :3000
9- `npm run typecheck` — type check only, no build
10- `npm run test` — Vitest unit tests
11
12# Conventions
13
14- ES module imports only (no require)
15- Use ~/ alias for app/, never relative paths
16- Form submissions go to Notion via app/models/Lead.server.ts
17
18# Anti-patterns
19
20- Never use React.FC — plain function components with typed props
21- Never commit .env — use .env.example instead
22- Never use any — fix the type or use unknown

One Thing to Know Before It Grows

Project-root CLAUDE.md is one of the few things re-injected from disk after a session compacts, which is exactly why load-bearing rules belong here rather than in chat or behind path-scoped frontmatter. It is also a fixed cost paid on every turn of every session, so target under 200 lines and move anything longer into a skill or a scoped rule. The Context Budget covers the tradeoff and how to measure your own.

Source

• Claude Code Memory Docscode.claude.com (opens in a new tab)