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

# Stack

- React Router v7, TypeScript, Tailwind CSS
- Node >= 24.0.0

# Commands

- `npm run dev` — start dev server on :3000
- `npm run typecheck` — type check only, no build
- `npm run test` — Vitest unit tests

# Conventions

- ES module imports only (no require)
- Use ~/ alias for app/, never relative paths
- Form submissions go to Notion via app/models/Lead.server.ts

# Anti-patterns

- Never use React.FC — plain function components with typed props
- Never commit .env — use .env.example instead
- Never use any — fix the type or use unknown

Source

Claude Code Memory Docs