CLAUDE.md Template: Next.js 16 + CockroachDB + Auth0 + Prisma

Overview

This CLAUDE.md Template page provides a concrete, copyable CLAUDE.md example for building a modern Next.js 16 application that uses CockroachDB as a distributed SQL database, Auth0 for authentication, and Prisma ORM for data access. It is designed for developers who want an actionable starting point and enforceable rules to ensure a secure, scalable, and maintainable stack.

When to Use This CLAUDE.md Template

• You are starting a production-ready Next.js 16 app with a distributed SQL database.
• You need coherent authentication with Auth0 across pages and APIs.
• You want a type-safe, ergonomic data layer via Prisma against CockroachDB.
• You require a clear set of architecture and security rules for Claude Code to follow.
• You plan to deploy to a modern hosting platform with proper CI/CD and secrets management.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a Claude Code engineer tasked with producing a production-ready Next.js 16 application that uses CockroachDB as a distributed SQL database, Auth0 for authentication, and Prisma ORM for data access.

Architecture rules:
- Use Next.js 16 App Router with server components where appropriate.
- Connect to CockroachDB via Prisma with a single DATABASE_URL and SSL required.
- Centralize configuration in lib/config.ts; avoid hard-coded secrets.
- Prefer API route handlers under app/api for server-side logic; keep UI logic in app/(...) components.
- Use a single Prisma Client instance exposed via lib/prisma.ts in the server scope.

File structure rules:
- app/ as the App Router entry point
- app/routes minimal; put route-level data fetching in server components
- prisma/ with schema.prisma and migrations
- lib/ for config, database client, and utilities
- components/ for UI pieces used across pages
- middleware.ts for basic route protection if needed

Authentication rules:
- Use Auth0 with Next.js middleware to protect API routes and pages.
- Enforce authenticated sessions for protected resources; store sessions in secure, HttpOnly cookies.
- Validate and propagate user roles/permissions from Auth0 to API endpoints when required.

Database rules:
- CockroachDB is the distributed SQL database; connect via Prisma using DATABASE_URL with SSL enabled.
- Define Prisma models in prisma/schema.prisma; generate client with npx prisma generate.
- Use migrations for schema changes; seed data in CI for staging.

Validation rules:
- Use zod for runtime validation of API inputs and server actions.
- Validate inputs strictly and return meaningful yet safe errors in production.

Security rules:
- Do not log secrets; use environment variables for all sensitive data.
- Enable CSRF protection on API routes; use sameSite cookies.
- Ensure HTTPS in production and proper CORS settings.

Testing rules:
- Unit tests for utilities and validation schemas.
- Integration tests for API routes (Auth0-protected endpoints) and Prisma data access.
- End-to-end tests for login, data creation, and data retrieval flows.

Deployment rules:
- Deploy to a platform like Vercel; configure AUTH0_DOMAIN, AUTH0_CLIENT_ID, DATABASE_URL, and PRISMA_ environment values.
- Run prisma generate and prisma migrate on deploy; seed staging data when applicable.
- Do not deploy with hard-coded credentials; verify secret management in CI.

Things Claude must not do:
- Do not bypass authentication or authorization checks.
- Do not connect to non-production databases without explicit flags.
- Do not produce raw SQL without parameterization.
- Do not assume internal network access; respect sandboxed deployment environments.

Recommended Project Structure

my-app/
  app/
    layout.tsx
    page.tsx
    /api
      hello.ts
    /components
      Header.tsx
    /styles
      globals.css
  prisma/
    schema.prisma
    migrations/
  lib/
    config.ts
    prisma.ts
    db.ts
  middleware.ts
  .env
  package.json
  README.md

Core Engineering Principles

• Type-safe and explicit contracts across API boundaries
• Incremental, testable changes with clear rollbacks
• Security by default: minimize surface area and secrets exposure
• Operational excellence: observability, logging, and tracing
• Reproducible builds and migrations

Code Construction Rules

• Always use Prisma for data access; do not bypass ORM; never write raw queries without parameterization.
• API handlers must validate inputs with zod; forward sanitized errors to clients.
• Authentication checks are mandatory on protected routes; do not skip middleware.
• Environment-specific configuration must live in environment variables; no hard-coded values.
• Secret values must never be logged; avoid printing stack traces in production.

Security and Production Rules

• Enable HTTPS in production and enforce Secure cookies with SameSite attributes.
• Use Auth0 roles/permissions to gate API endpoints; never grant broad access.
• Protect database credentials; store in CI/CD secret stores; rotate credentials regularly.
• Implement CSRF protection for state-changing operations; validate origin headers for API calls.

Testing Checklist

• Unit tests for validators and utilities
• Integration tests for Prisma data access and CockroachDB connectivity
• Authentication tests verifying Auth0 login flow and session persistence
• CI checks for prisma generate, migrations, type checks, and linting
• End-to-end tests for critical user journeys

Common Mistakes to Avoid

• Overlooking environment-based configuration and secret handling
• Ignoring distributed SQL considerations in CockroachDB (distributed transactions, latency)
• Not validating inputs; leaking sensitive error messages
• Hard-coding URLs or credentials in code or migrations

FAQ

• What is this CLAUDE.md Template for? A starting blueprint for building a Next.js 16 app with CockroachDB, Auth0, and Prisma, expressed as a CLAUDE.md template.
• Do I need CockroachDB to run this template? Yes; the template assumes CockroachDB as the distributed SQL DB and uses Prisma to access it.
• How is Auth0 configured? Auth0 is wired through Next.js middleware and API routes; client IDs and domains come from environment variables.
• Can I adapt this to other ORMs? The template is Prisma-focused; adapt the Prisma models and client usage if switching ORMs.
• Where are secrets stored? In environment variables or secret stores in CI/CD; never in code.
• How do I test authentication? Use integration tests around protected routes and a mocked Auth0 workflow in CI.