Walkthrough

Anatomy of a CLAUDE.md

The five sections every solid CLAUDE.md has, with examples.

Steps · 0 / 5 done

Section 1 — Stack

Top of file. Explicit and boring. Frameworks, language versions, package manager, runtime. The agent uses this to pick the right idioms.

## Stack
- Next.js 15 (App Router) on Node 20
- TypeScript strict, no `any`
- Tailwind v3 + shadcn/ui
- pnpm (never `npm install`)
- Tests: vitest + @testing-library/react

Section 2 — Conventions

Naming, import order, file layout, error patterns. The stuff humans pick up from reading old PRs.

## Conventions
- camelCase for vars and functions, PascalCase for components
- Imports: external, then `@/`, then relative — alphabetical within each group
- Never throw raw `Error`. Use `AppError` from src/lib/errors.
- Server components by default. `"use client"` only when needed.

Section 3 — Commands
How to run the project, run tests, lint, build. The agent will use these when you ask it to verify a change.
```
## Commands
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint --max-warnings 0`
- Build: `pnpm build`
```

Section 4 — Negative constraints

What the agent must never do. Be specific. 'Don't break things' is useless; 'Never commit .env.local' is actionable.

## Never
- Never commit secrets. .env.local is gitignored — keep it that way.
- Never run `npm install` (we use pnpm).
- Never edit files under `prisma/migrations/` directly.
- Never disable a failing test to make CI green.

Section 5 — Tacit knowledge

The 'wait, but actually' stuff. Quirks, gotchas, why-it-is-this-way. Save the next engineer a week of debugging.

## Gotchas
- Auth tokens live in HttpOnly cookies, not localStorage. Don't read them from JS.
- The /admin routes use a different middleware. Check src/middleware.ts when touching them.
- Image uploads go through R2, not local disk. Use the existing upload util.

· Tick off the 5 step(s) above.