<!--
  CLAUDE OS: CODING PROJECT TEMPLATE
  ==================================
  Where to put it: the root of your repo as ./CLAUDE.md (commit it so your team shares it).
  Private notes you don't want to commit (local URLs, test accounts): ./CLAUDE.local.md + add it to .gitignore.

  Fastest start: run /init inside Claude Code first. It scans your repo and writes a starting CLAUDE.md.
  Then merge in the sections from this template that /init can't discover on its own
  (the "why", the rules, the don'ts).

  Keep it under ~200 lines (Anthropic's own guidance). It loads into every session.
  Put multi-step procedures (deploy, release, migrations) in skills: they load only when needed.
  Use @path/to/file to import a doc, e.g. @docs/architecture.md (imports also load at startup, so keep them small).
  Delete these comments when you're done.
-->

# [PROJECT NAME]

<!-- WHY: 2-3 lines so Claude understands what matters before touching code. -->
[One sentence: what this app does and for whom, e.g., "Checkout pages for Shopify merchants. Paying customers depend on uptime; payments code is the most sensitive area."]

## Stack
<!-- WHY: stops Claude from guessing versions or importing libraries you don't use. -->
- [e.g., Next.js 16 (App Router), React 19, TypeScript strict, Tailwind v4]
- [e.g., Postgres via Drizzle ORM; migrations in /drizzle]
- [e.g., Auth: Better Auth. Payments: Stripe. Hosting: Vercel]
- Package manager: [pnpm / npm / bun / uv]. Never use a different one.
- [If a framework version is newer than the model's training data: "Next 16 differs from older versions: read node_modules/next/dist/docs before non-trivial changes."]

## Commands
<!-- WHY: the #1 thing Claude needs to verify its own work. Use exact commands. -->
- Install: `[pnpm install]`
- Dev server: `[pnpm dev]` (runs on [http://localhost:3000])
- Typecheck: `[pnpm typecheck]`
- Lint: `[pnpm lint]`
- Tests: `[pnpm test]` · single file: `[pnpm test path/to/file.test.ts]`
- E2E: `[pnpm e2e]`
- DB migration: `[pnpm db:migrate]`

## Project map
<!-- WHY: saves Claude from reading dozens of files to find its way. Only the important folders. -->
- `[src/app/]` routes and pages
- `[src/lib/]` shared helpers ([e.g., auth.ts, db.ts, stripe.ts])
- `[src/components/ui/]` design system components. Reuse these; don't create new buttons/inputs.
- `[src/server/]` server-only code (never import from client components)

## Rules
<!-- WHY: the conventions a new developer would get wrong in week one. -->
- Before saying a task is done: run typecheck, lint and the relevant tests. Report what you ran and the result.
- Make the smallest change that solves the problem. Don't refactor unrelated code in the same change.
- Follow the patterns in existing files. When unsure, find a similar file and copy its structure.
- [e.g., "Money is stored as integer cents. Never use floats for money."]
- [e.g., "All server actions validate input with zod."]
- [e.g., "New pages must work at 375px wide."]
- For any non-trivial task, propose a short plan first and wait for my OK (or use plan mode).

## Danger zones
<!-- WHY: tell Claude where mistakes are expensive, so it slows down there. -->
- `[src/server/payments/]`: ask before changing anything here.
- `[drizzle/ migrations]`: never edit an existing migration; create a new one.
- Never run `[destructive command, e.g., db:reset, git push --force]` without asking.
- Never commit `.env*` files or print secrets.

## Git
- Branch naming: `[feat/short-name, fix/short-name]`
- Commit style: `[Conventional Commits, e.g., "fix: handle empty cart"]`
- Don't commit or push unless I ask.

## Compact instructions
<!-- WHY: when the conversation gets compacted, Claude keeps what you list here. -->
When compacting, keep: the current task goal, files changed, test results, and open decisions.

## Known gotchas
<!-- WHY: every time Claude makes the same mistake twice, add one line here. This section is how the file gets smarter. -->
- [e.g., "The dev server must be restarted after changing env vars."]
- [e.g., "Tests need `TZ=UTC` or date tests fail."]