CLAUDE.md template for Next.js

# Next.js app

A Next.js app using the App Router and TypeScript. Change any command below that differs from the scripts in package.json.

## Commands

```bash
npm install  # install dependencies
npm run dev  # start the dev server
npm run lint  # lint
npx tsc --noEmit  # type-check
npm test  # run the tests
npm run build  # production build, run before calling a change done
```

Run the tests and the linter after every code change, and fix failures before saying a task is done.

## Layout

- Routes and layouts live in app/. A folder is a route; page.tsx renders it and route.ts handles API requests.
- Shared UI goes in components/, helpers in lib/. Keep server-only code out of files marked use client.
- Components are server components by default. Add use client only when a component needs state or browser APIs.

## Conventions

- TypeScript strict mode. No any without a comment saying why.
- Validate request bodies and query params at the route boundary before using them.
- Read environment variables in one place and fail loudly when a required one is missing. Only variables prefixed NEXT_PUBLIC_ may reach the browser.
- Match the style of the file you are editing. Do not reformat files you did not change.

## Database

- Database changes go through migration files in the repo. Never edit a migration that has shipped; add a new one.
- Never run destructive schema commands (db push, drop, reset) against a shared or production database.
- Show me the SQL or schema change before applying it.

## Secrets

- Never read, print, edit or commit .env files, credentials, API keys or private keys.
- Use placeholder values in examples and tests. If a secret shows up in a file or a log, stop and tell me.

## Deploys

- Never deploy to production. I run production deploys myself.
- Preview deploys are fine only when I ask. Do not change deployment settings or environment variables on the host.

## Git

- Make small commits on a branch and write messages that say why the change was made.
- Never run git push --force, git reset --hard, git clean, git checkout -- <file>, git stash or git rebase, and never use --no-verify. Ask first.
- Do not push unless I ask.

## Do not touch

- Lockfiles (package-lock.json and similar): do not edit by hand, and do not add or upgrade dependencies without asking.
- Generated folders (.next/, node_modules/) and anything marked generated or do not edit.
- next.config.js and the CI workflow files: do not change without asking.

# AGENTS.md: Next.js app

Instructions for any coding agent working in this repository. A Next.js app using the App Router and TypeScript. Change any command below that differs from the scripts in package.json.

## Commands

```bash
npm install  # install dependencies
npm run dev  # start the dev server
npm run lint  # lint
npx tsc --noEmit  # type-check
npm test  # run the tests
npm run build  # production build, run before calling a change done
```

Run the tests and the linter after every code change, and fix failures before saying a task is done.

## Layout

- Routes and layouts live in app/. A folder is a route; page.tsx renders it and route.ts handles API requests.
- Shared UI goes in components/, helpers in lib/. Keep server-only code out of files marked use client.
- Components are server components by default. Add use client only when a component needs state or browser APIs.

## Conventions

- TypeScript strict mode. No any without a comment saying why.
- Validate request bodies and query params at the route boundary before using them.
- Read environment variables in one place and fail loudly when a required one is missing. Only variables prefixed NEXT_PUBLIC_ may reach the browser.
- Match the style of the file you are editing. Do not reformat files you did not change.

## Database

- Database changes go through migration files in the repo. Never edit a migration that has shipped; add a new one.
- Never run destructive schema commands (db push, drop, reset) against a shared or production database.
- Show me the SQL or schema change before applying it.

## Secrets

- Never read, print, edit or commit .env files, credentials, API keys or private keys.
- Use placeholder values in examples and tests. If a secret shows up in a file or a log, stop and tell me.

## Deploys

- Never deploy to production. I run production deploys myself.
- Preview deploys are fine only when I ask. Do not change deployment settings or environment variables on the host.

## Git

- Make small commits on a branch and write messages that say why the change was made.
- Never run git push --force, git reset --hard, git clean, git checkout -- <file>, git stash or git rebase, and never use --no-verify. Ask first.
- Do not push unless I ask.

## Do not touch

- Lockfiles (package-lock.json and similar): do not edit by hand, and do not add or upgrade dependencies without asking.
- Generated folders (.next/, node_modules/) and anything marked generated or do not edit.
- next.config.js and the CI workflow files: do not change without asking.