CLAUDE.md

Next.js 15 (App Router) + TypeScript + Tailwind + Postgres via Drizzle. Hermes reads this as its fallback project file; other agents read it natively — keep it tool-agnostic.

Commands

pnpm dev          # dev server on :3000
pnpm build        # production build — run before claiming a change works
pnpm typecheck    # tsc --noEmit
pnpm lint         # eslint
pnpm db:migrate   # apply drizzle migrations
pnpm db:studio    # inspect the database

Conventions

• Server Components by default; 'use client' only where there is real interactivity, and as deep in the tree as possible.
• Data access goes through lib/queries/ — components never import the Drizzle client directly.
• Route handlers validate input with the zod schemas in lib/schemas/; a handler that trusts its body fails review.
• Environment variables are read once in lib/env.ts (validated at boot), never via bare process.env in feature code.

Traps

• next build succeeds with type errors silenced in next.config.ts — run pnpm typecheck separately; the build passing proves little.
• Route segment config (revalidate, dynamic) must be a literal, not a computed value — computed values are silently ignored.
• Middleware runs on the Edge runtime: no Node APIs there, and it will fail at deploy time, not locally.

Verification

A change is done when pnpm typecheck && pnpm lint && pnpm build pass and the affected route was actually loaded in the dev server.