Every repo I touch gets a CLAUDE.md at the root. It is the difference between an agent that guesses at the house style and one that already knows it. Short, blunt, and mostly a list of constraints — the agent reads it before the first edit.
# CLAUDE.md — read before writing any code.
## Stack
- Postgres-first. No new datastore without an RFC.
- TypeScript everywhere. Strict mode, no `any`.
- Tests are the spec — write the failing test first.
## Invariants
- Every mutation carries an idempotency key, enforced server-side.
- All money is integer cents. Never a float.
- Migrations ship with deploy order, checks, and a forward-fix plan.
## Never
- Add a queue, cache, or service before product evidence demands it.
- Log secrets, tokens, or full request bodies.
- Touch db/migrations/\*\* without reading skills/migration-review.
## Style
- Small PRs. One concern each. Easy to review, test, and ship.
- Comments explain why, never what.Keep it short#
If a line does not change behavior, it does not belong here. The file is read on every task, so every line costs attention. I keep it under a screen — constraints, not documentation.
Constraints beat instructions#
“Never add a queue before product evidence” travels further than a paragraph on architecture philosophy. Negative rules are easy to check and hard to misread. The agent obeys a checklist far more reliably than a vibe.
What earns a line#
The file should hold rules that change a future edit: runtime choices, protected boundaries, test commands, data invariants, and known traps. It should not hold a tour of the repo.
When a rule gets violated twice, promote it here. When a rule stops mattering, delete it. Project memory has to stay sharp or it becomes another stale doc the agent learns to skim.