Prompting Claude Code: CLAUDE.md Patterns & Project Instructions

# Project Name

Brief one-line description of what this project is.

## Commands

| Command | What it does |
|---|---|
| `npm run dev` | Start dev server |
| `npm run lint` | ESLint + Prettier |
| `npm run test` | Vitest |

## Architecture

[High-level architecture: folder structure, data flow, key design decisions]

## Conventions

[Coding conventions, naming patterns, file organization, preferred libraries]

## Constraints

[Hard rules: what NOT to do, deployment restrictions, API limitations]

## Commands

| Command | What it does | Safe to run? |
|---|---|---|
| `npm run dev` | Start dev server on port 3000 | Yes |
| `npm run lint` | ESLint check | Yes |
| `npm run test` | Run test suite | Yes — never skip |
| `npm run build` | Production build | Yes |
| `npm run db:migrate` | Run database migrations | ASK FIRST — affects production schema |
| `npm run deploy` | Deploy to production | NEVER run without explicit instruction |

## Architecture

- **Next.js 14 App Router** — pages in `app/`, API routes in `app/api/`
- **Prisma ORM** — schema in `prisma/schema.prisma`, migrations in `prisma/migrations/`
- **tRPC** — API layer: routers in `server/api/routers/`, procedures use Zod validation
- **Auth** — NextAuth.js with GitHub + Google providers, session in `server/auth.ts`
- **State** — React Query for server state, Zustand for client state
- **Styling** — Tailwind CSS, component library in `components/ui/`

Data flow: `Page → tRPC query → Prisma → PostgreSQL`
Mutation flow: `Form → tRPC mutation → Zod validation → Prisma → PostgreSQL → React Query invalidation`

## Conventions

### Code style
- Use `const` over `let`; avoid `var`
- Prefer arrow functions for callbacks, named functions for components
- Early returns over nested ifs
- No `any` types — use `unknown` and type guards

### File naming
- Components: `kebab-case.tsx` (e.g., `user-profile.tsx`)
- Utilities: `camelCase.ts` (e.g., `formatDate.ts`)
- Types: `PascalCase.ts` (e.g., `UserTypes.ts`)

### Component patterns
- "use client" directive at top of file when needed
- Props interface exported, named `{ComponentName}Props`
- Use `cn()` utility for conditional classes

### Git
- Branch naming: `feature/description`, `fix/description`, `chore/description`
- Commit messages: conventional commits (`feat:`, `fix:`, `chore:`)
- NEVER commit `.env` files or secrets

## Constraints

### NEVER
- Use `any` as a TypeScript type — use `unknown` and type guards
- Import from `@/lib/internal` — this module is deprecated
- Modify `prisma/schema.prisma` without asking — requires migration
- Add new npm dependencies without listing them first for approval
- Commit directly to `main` — always create a branch
- Use `console.log` in production code — use the logger utility

### ALWAYS
- Run `npm run lint` after making changes
- Run `npm run typecheck` if TypeScript files were modified
- Write tests for new features (files in `__tests__/` next to the source)
- Update the PR description if scope changes mid-implementation

### ENVIRONMENT
- Node 20, npm 10
- PostgreSQL 16
- Redis 7 for caching and session store

Error handling patterns:
- API routes: return `{ error: string }` with appropriate HTTP status
- tRPC procedures: throw `TRPCError` with code and message
- Client components: use error boundaries; show toast for mutations
- Never swallow errors silently — always log with `logger.error()`

Test patterns (Vitest):
- Unit tests: `describe('functionName', () => { it('behavior', () => { ... }) })`
- Component tests: use `@testing-library/react`, test behavior not implementation
- API tests: use `testcontainers` for Postgres; clean up after each test suite
- Naming: `it('returns X when given Y')` not `it('should work')`

Before considering a task complete, verify:
- [ ] `npm run lint` passes
- [ ] `npm run typecheck` passes
- [ ] `npm run test` passes
- [ ] New code follows existing patterns (check neighboring files)
- [ ] No commented-out code left behind
- [ ] No `console.log` or `debugger` statements
- [ ] Git diff reviewed for accidental changes