CLAUDE.md — the file that makes Claude Code actually understand your project

Every Claude Code session starts with a fresh context window — it doesn't remember last session. But there's a trick: a file called CLAUDE.md that Claude reads at the start of every conversation.

Think of it as a briefing document for your AI teammate. You put it in your project root and fill it with things you'd tell a new developer: build commands (npm run dev), coding standards ("use 2-space indentation"), architecture decisions ("API handlers live in src/api/handlers/"), and common pitfalls.

The power move: scope instructions to specific files. Put rules in .claude/rules/ with frontmatter like paths: ["src/api//*.ts"] and those rules only activate when Claude works on matching files. This keeps context lean and instructions precise.

There's also a user-level ~/.claude/CLAUDE.md for personal preferences that apply to all your projects — like "always use pnpm, not npm."