CLAUDE.md Template: Next.js 16 + Neon Serverless Postgres + Clerk Auth + Drizzle ORM Pipeline

Overview

What is this CLAUDE.md template? It is a copyable Claude Code blueprint for building a production-grade Next.js 16 app using Neon Serverless Postgres, Clerk authentication, and Drizzle ORM. It provides a complete pipeline layout and implementation constraints that you can paste into a CLAUDE.md file to drive code generation, reviews, and deployment.

Stack coverage: Next.js 16 app router, Neon Serverless Postgres, Clerk authentication, Drizzle ORM, and a serverless deployment pipeline.

Direct answer: This CLAUDE.md template delivers a ready-to-paste instruction block plus a structured project layout and rules to implement a secure, scalable full-stack flow with the specified stack.

When to Use This CLAUDE.md Template

• You are starting a new Next.js 16 project that targets Neon Serverless Postgres for the database.
• You require Clerk-based authentication integrated into a TypeScript Next.js app.
• You want to use Drizzle ORM for database access with a clean schema layer.
• You need an opinionated, copyable CLAUDE.md template to enforce architecture and deployment rules.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a Production Engineer who designs and enforces a Next.js 16 + Neon Serverless Postgres + Clerk Auth + Drizzle ORM pipeline with Claude Code. Produce precise, copyable code blocks and configuration scripts.

Architecture rules:
- Use Next.js 16 app router with server components where appropriate; isolate client components behind Clerk auth checks.
- Centralize DB access via Drizzle ORM. Do not use raw SQL in app layer except for advanced migrations.
- Use a single Neon Serverless Postgres DSN from environment variables (NEON_DATABASE_URL).
- Authentication must be handled by Clerk; protect API routes with Clerk middleware.
- All data access must be type-safe via Drizzle models and TypeScript types.
- Expose only necessary APIs; minimize surface area in API routes.

File structure rules:
- Place application code under app/ for Next.js 16.
- Place database schema and drizzle setup under drizzle/.
- Place shared utilities under lib/.
- Do not include legacy Prisma or Mongoose configs.

Authentication rules:
- Use Clerk's Next.js SDK; protect pages and API routes with the  and withServerSideAuth where needed.
- Do not place private Clerk keys in client code; retrieve them from environment variables at build time.

Database rules:
- Use Drizzle ORM models for all data access.
- Migrate with drizzle migrate; do not run raw migrations from application code.
- Use parameterized queries; never interpolate user input into SQL strings.

Validation rules:
- Validate inputs with zod schemas; export inferred TS types for API handlers.
- Sanitize all user input before persistence.

Security rules:
- Store secrets in environment variables; never check them into git.
- Use HTTPOnly cookies for sessions; enforce CSRF protection where applicable.
- Enable TLS in deployment; disable verbose error messages in production.

Testing rules:
- Unit test API handlers with Vitest; mock Clerk and DB calls.
- Integration tests for data layer using an in-memory or test Neon database.
- Include end-to-end tests that cover auth flows and key business paths.

Deployment rules:
- Deploy to a serverless host (e.g., Vercel) with environment variables NEON_DATABASE_URL, CLERK_FRONTEND_API, CLERK_API_KEY, NEXTAUTH_URL, and any secrets.
- Use CI to run tests on PRs; ensure type-safety and lint checks pass before merge.

Things Claude must not do:
- Do not bypass Clerk authentication checks.
- Do not expose database credentials in client-side code.
- Do not generate unsafe SQL via string concatenation.
- Do not configure Prisma or Mongoose in this project.
- Do not hard-code production secrets.
  

Recommended Project Structure

.
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   ├── globals.css
│   └── api/
│       └── auth/
│           └── route.ts
├── components/
│   ├── Navbar.tsx
│   └── Provider.tsx
├── drizzle/
│   ├── index.ts
│   ├── schema.ts
│   └── migrations/
├── lib/
│   ├── db.ts
│   └── drizzle.ts
└── drizzle.config.ts

Core Engineering Principles

• Explicit type-safety and thorough validation with zod and Drizzle types.
• Clear separation of concerns: app layer, data layer, and auth layer.
• Environment-driven configuration and 12-factor principles.
• Automated tests for API, data access, and deployment.
• Security-by-default: least privilege, CSRF protection, and TLS.

Code Construction Rules

• Use Drizzle ORM for all DB access and migrations; never rely on string-interpolated SQL in code paths.
• All API routes must be protected by Clerk middleware; unprotected routes are prohibited.
• Use environment variables for secrets (NEON_DATABASE_URL, CLERK_API_KEY, etc.).
• Do not commit database connection strings to git; use runtime fetch of secrets.
• Validate and sanitize inputs with zod before hitting the data layer.

Security and Production Rules

• Enable CSRF protection for state-changing requests.
• Use HTTPOnly cookies and secure flags in all environments.
• Serverless deployments must not leak stack traces in production.
• Audit trails for authentication events and harmful input attempts should be available to operators.

Testing Checklist

• Unit tests for Drizzle models and API handlers.
• Integration tests for data access with a test Neon database or mocks.
• End-to-end tests for Clerk auth flows and core UI paths.
• CI must run type checks, lint, unit, and integration tests on PRs.

Common Mistakes to Avoid

• Mixing client and server DB code; ensure DB access occurs on server side only where appropriate.
• Using raw SQL in business logic without parameterization.
• Hard-coding secrets or using insecure secret patterns.
• Over-sharing data in API responses; always enforce authorization at the API boundary.

FAQ

Q: What is this CLAUDE.md Template for?

A: It provides a ready-to-paste blueprint for Next.js 16 with Neon Serverless Postgres, Clerk Auth, and Drizzle ORM, including architecture rules and deployment guidance.

Q: Which parts should I paste into CLAUDE.md?

A: The entire code block under Copyable CLAUDE.md Template plus the related project structure and rules sections you want to enforce.

Q: How do I configure Neon with Next.js?

A: Use NEON_DATABASE_URL in environment variables and connect via Drizzle to the database.

Q: How is authentication handled?

A: Clerk authentication is integrated through Clerk Next.js SDK and middleware for protected routes.

Q: What tests should I run?

A: Unit tests for data layer, integration tests against Neon, and E2E tests for auth and core features.