CLAUDE.md Best Practices

A CLAUDE.md file is the memory Claude Code reads before it touches your project. Get it right and the agent stops asking obvious questions and stops breaking your conventions. Get it wrong and you are paying token cost on noise that makes the model worse.

The official memory docs explain the loading hierarchy: a personal file, a project file at the repo root, and nested files in subfolders that layer on top. Read the memory reference before you write a single line.

Keep it short

Every line in CLAUDE.md costs context on every turn. If a rule does not change behavior, delete it. Aim for the smallest file that still prevents the mistakes you actually see.

# Project: payments-api

## Stack
- TypeScript, NestJS 11, Postgres via Prisma
- Tests: vitest. Run `npm test` before claiming done.

## Conventions
- Money is always integer cents, never floats.
- All routes return the `ApiResponse<T>` envelope.
- Never edit `prisma/migrations/` by hand.

## Commands
- Dev: `npm run dev`
- Typecheck: `npm run typecheck`

Be specific, not aspirational

Write rules the model can verify and follow. "Write clean code" does nothing. "Money is integer cents, never floats" is a constraint the model can actually obey. The Builder.io guide on this calls out the same trap: vague guidance reads well and changes nothing.

Maintain it like code

1. When the agent makes the same mistake twice, add a rule instead of correcting it again.
2. Delete rules for code that no longer exists.
3. Review the file in PRs the same way you review source.

26:11

The best CLAUDE.md is the one you keep deleting from. Every rule earns its place by preventing a real mistake.