Write a CLAUDE.md that makes Claude Code actually useful

What CLAUDE.md is

Claude Code reads a CLAUDE.md file from your project root at the start of every session. Anything in it is treated as standing instructions, so it's the cheapest way to stop repeating yourself.

Run /init inside Claude Code to generate a first draft from your repo, then edit it by hand. The generated version is a starting point, not the finished article.

What to put in it

Keep it short and specific. The highest-value lines are:

1. 1Exact commands: how to install, run dev, run tests, lint and type-check
2. 2Architecture in a few lines: where things live and why
3. 3Conventions: naming, error handling, which libraries to prefer
4. 4Hard rules: files never to edit, commands never to run, secrets to leave alone
5. 5How to verify work: what "done" means for a change

A template to start from

# Project: invoice-api

## Commands
- Install: pnpm install
- Dev: pnpm dev (port 3000)
- Test: pnpm test -- --run   (single file: pnpm test path/to/file)
- Types: pnpm typecheck

## Layout
- src/routes   HTTP handlers, thin
- src/services business logic, unit tested
- src/db       Prisma schema + queries only

## Conventions
- TypeScript strict, no `any`
- Money is integer pence, never floats
- Prefer existing helpers in src/lib before adding dependencies

## Never
- Edit prisma/migrations by hand
- Commit .env files or print secrets

## Done means
- Tests and typecheck pass
- New logic has a test

Keep it alive

Every time you correct the agent for the same thing twice, add a line. Every time a line stops being true, delete it. A stale CLAUDE.md is worse than none, because it gives confident wrong instructions.