# CLAUDE.md — project memory (template)

> Drop this file at the root of your repo. Most AI coding tools read it
> automatically at the start of every session. It is *your* memory standing in
> for the AI's — the single cheapest way to stop it re-making the same mistakes.
> Delete the guidance comments and fill in your project's reality.

## What this project is
<!-- One paragraph: what it does, who uses it, what "good" looks like. -->

## Stack & commands
- Language / framework:
- Install: `...`
- Run: `...`
- Test: `...`            <!-- the AI should run this before claiming "done" -->
- Lint / typecheck: `...`

## Invariants — never break these
<!-- The rules that are non-obvious and expensive to get wrong. Be specific.
     The AI respects what is written and quietly violates what is merely implied. -->
- e.g. "All money is integer minor units (cents), never floats — rounding is explicit and tested."
- e.g. "Never call the payments API without an idempotency key."
- e.g. "Migrations are forward-only; never edit a shipped migration."
- e.g. "No PII (names, account numbers, emails) in logs, prompts, or error messages — scrub at the boundary."
- e.g. "Every external/AI call is logged with inputs, outputs and a correlation id — an action that isn't auditable didn't happen."
- e.g. "Amounts crossing a boundary carry their currency explicitly; never assume a default."

## Known issues / sharp edges
<!-- Things that have already burned someone. Saves the AI from rediscovering them. -->
- e.g. "The cache is not invalidated on bulk update — see lessons-log."

## Conventions
- Error handling: handle at boundaries (user input, external APIs); trust internal code.
- Style: small files (<400 lines), small functions (<50 lines), no dead code paths.
- Tests: the test is the spec. If the code disagrees with the test, the code is wrong.

## How to verify a change here
<!-- The exact commands/queries that PROVE a change works — not "should work". -->
1. Run the test suite: `...`
2. Check the distribution, not just the aggregate: `...`
3. Prove it actually ran (logs / a row in the DB / a real output), don't assume.

## Definition of done
- [ ] Tests pass (and a new test exists for the change)
- [ ] Lint/typecheck clean
- [ ] No secrets, no debug prints
- [ ] Verified with real data, not intent