CLAUDE.md for Next.js + Supabase
App Router, TypeScript, Tailwind and Supabase with row-level security.
How to use this
Save it as CLAUDE.md in your repository root and replace the placeholders in angle brackets. Claude reads it before every task, so keep it short — the Playbooks table at the bottom is how you add detail without paying for it on every unrelated request.
The file
# <project name>
<One or two sentences: what this app does and who uses it.>
## Commands
- `npm run dev` — dev server
- `npm run build` — production build; must pass before any push
- `npm run typecheck` — TypeScript, no emit
- `npm test` — unit tests
## Architecture
- `src/app` — App Router pages and route handlers
- `src/components` — React components (PascalCase, one per file)
- `src/lib` — shared utilities (camelCase)
- Use the `@/` path alias for all imports.
## Conventions
IMPORTANT: Server Components by default. Add `'use client'` only for interactivity.
YOU MUST: use `supabase.auth.getUser()` in server components, never `getSession()`.
NEVER: commit `.env.local` or a service role key.
- Row-level security is always on. Filter soft deletes with `.eq('is_deleted', false)`.
- Add shadcn/ui components via the CLI; do not hand-write files in `components/ui/`.
## Verification
Run `npm run build` and `npm run typecheck`. Both must pass.
## Working with Claude Code
- Explore the relevant files before proposing a change.
- For anything non-trivial, plan first (Shift+Tab into plan mode) and let me review.
- Run the verification command below before telling me something works.
- Keep commits small and conventional (`feat:`, `fix:`, `docs:`, `chore:`).
## Playbooks
- Changing the database schema → read `.claude/playbooks/db-migration.md` first
- Cutting a production release → read `.claude/playbooks/release.md` first
The playbooks it expects
The routing table points at files that don't exist yet. Create them as you need them — each one holds a procedure too long to sit in CLAUDE.md and too rare to justify the context cost.
.claude/playbooks/db-migration.mdChanging the database schema.claude/playbooks/release.mdCutting a production release
Other starting points
R Data Analysis
Tidyverse analysis project with reproducible figures and a clear data pipeline.
Python Research Project
Analysis codebase with notebooks for exploration and modules for anything reused.
Python REST API
FastAPI service with typed schemas, tests and migrations.
CLI Tool
A command-line tool where the interface is the contract.
Monorepo
Several packages in one repository, where knowing the boundaries matters most.
Need something else? Build one from scratch with the generator.