CLAUDE.md Template: Next.js 16 + PlanetScale MySQL + WorkOS Auth + Prisma ORM

Overview

The CLAUDE.md template is a copyable Claude Code blueprint designed for developers building a Next.js 16 application that uses PlanetScale MySQL for data, WorkOS for authentication, and Prisma ORM for data access. This page provides a ready-to-paste CLAUDE.md template along with a recommended project structure and rules tuned for this stack.

When to Use This CLAUDE.md Template

• When starting a new Next.js 16 project that requires scalable MySQL storage.
• When integrating WorkOS authentication and authorization in a multi-tenant app.
• When adopting Prisma ORM to talk to PlanetScale MySQL with safe migrations.
• When you want a copyable CLAUDE.md block to accelerate Claude Code tasks.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: Architect and lead developer for a Next.js 16 web app using PlanetScale MySQL, WorkOS Auth, and Prisma ORM. You will generate complete boilerplate and guidance for Claude Code tasks.
Architecture rules:
- Use Next.js 16 app directory with server components and edge caching where appropriate.
- Prisma ORM for database access; PlanetScale MySQL database; manage migrations with PlanetScale-compatible workflows.
- WorkOS for authentication and authorization; implement SSO and MFA where supported by policy.
- Environment variables and secrets must be handled securely; never commit secrets to VCS.
- Code should be modular with clear separation: apps/web, libs/, and prisma/.

File structure rules:
- apps/web/ for the Next.js 16 app (app/, components/, styles/)
- prisma/ for Prisma schema and migrations
- libs/ for shared UI and utilities
- scripts/ for migrations and infra tasks
- .env.example and .env.local templates

Authentication rules:
- Use WorkOS for authentication (SSO/OIDC) and enforce HttpOnly session cookies.
- Protect API routes and pages with middleware.
- Do not store tokens in localStorage or expose access tokens to the client.

Database rules:
- PlanetScale MySQL; connect via Prisma with DATABASE_URL; enable per-branch migrations and use shadow databases for tests.
- Use Prisma generate and type-safe client in server components only.

Validation rules:
- Use Zod for all input validations on API routes and form handling.
- Centralize shared schemas in a libs/validation module.

Security rules:
- Do not expose secrets in client bundles; use server-only environment variables.
- Enforce CSRF protection for state-changing requests when applicable.
- Limit CORS to trusted origins and limit API exposure.

Testing rules:
- Unit tests for API routes and utilities.
- Integration tests for Prisma queries against a test PlanetScale database.
- End-to-end tests with Playwright covering login flows and core user journeys.

Deployment rules:
- Deploy to Vercel with proper secrets; configure PlanetScale branch connections and run migrations in a safe flow.
- Ensure server components are SSR/CSR appropriate; enable edge caching where beneficial.

Things Claude must not do:
- Do not bypass authentication or store secrets in the client.
- Do not perform direct writes to production databases from the client.
- Do not omit migrations or bypass PlanetScale’s branching workflow.

Recommended Project Structure

apps/
  web/
    app/
      page.tsx
      layout.tsx
      globals.css
    components/
      Header.tsx
      Footer.tsx
    styles/
      globals.css
  prisma/
    schema.prisma
    migrations/
libs/
  ui/
    Button.tsx
    Input.tsx
scripts/
  migrate.sh
.env.example

Core Engineering Principles

• Type-safe end-to-end: TypeScript, Prisma, and Zod schemas everywhere.
• Explicit data flow: server components where possible; avoid unnecessary client fetches.
• Security-first by default: secret handling, auth, and validation baked in.
• Iterate quickly with CI that runs linting, tests, and type checks on PRs.
• Sustainable performance: edge caching, selective SSR, and database connection best practices.

Code Construction Rules

• Use Next.js 16 app directory for the main web app.
• Use Prisma ORM connected to PlanetScale MySQL; update schemas via migrations in a shadow database workflow.
• Integrate WorkOS SDKs for authentication and authorization flows.
• Enforce strict TypeScript types; avoid any in business logic.
• All environment variables must be defined in .env.* and referenced securely.
• Do not mix server and client code; isolate server-only operations behind API routes or server components.
• Prefer API routes for business logic and data fetching; use getServerSideProps or equivalent patterns accordingly.

Security and Production Rules

• HttpOnly cookies for sessions; do not expose auth tokens to the browser.
• CSRF protection on state-changing endpoints; use same-site cookies when possible.
• Limit CORS and origin exposure to trusted domains.
• Rotate database credentials and API keys; store in a secret manager in CI/CD.
• Audit logs for auth events and sensitive operations.

Testing Checklist

• Unit tests for API routes and utilities.
• Integration tests for Prisma queries against a test PlanetScale instance.
• End-to-end tests for login flows and core user journeys.
• CI checks include lint, type checks, and test suites.

Common Mistakes to Avoid

• Storing secrets in client code or repo history.
• Skipping migrations or bypassing PlanetScale branching workflow.
• Sending credentials or tokens to the client side.
• Using non-type-safe API responses or ignoring Zod schemas.

FAQ

• What is this CLAUDE.md Template for? A ready-to-paste CLAUDE.md block for a Next.js 16 + PlanetScale + WorkOS + Prisma stack.
• Which technologies are covered? Next.js 16, PlanetScale MySQL, WorkOS Auth, Prisma ORM.
• How do I customize it? Modify the CLAUDE.md block with your repo specifics and adapt the project structure.
• Where should the CLAUDE.md block go? At the repo root as shown in the template.
• What should I avoid? Exposing secrets, bypassing auth, or performing unguarded writes to production databases.