# The CLAUDE.md that keeps agents grounded

> A short project memory file for the stack, invariants, and the lines an agent must not cross.

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.

```md title="CLAUDE.md"
# 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.

<Tradeoff title="Short memory beats complete memory">
  A CLAUDE.md that tries to remember everything becomes another document nobody reads. Keep only the
  constraints that prevent expensive mistakes.
</Tradeoff>

### 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.