CLAUDE.md Template: Next.js + TS + Supabase + Clerk + Stripe NL SQL SaaS

Overview

Direct answer: This CLAUDE.md Template provides a copyable Claude Code instruction set for building a complete NL SQL SaaS with Next.js 16, TypeScript, Supabase as the database layer, Clerk for authentication, Stripe for payments, and chart outputs. It defines architecture rules, file structure, authentication and data access patterns, validation and security practices, testing, deployment, and explicit do-not rules to keep Claude aligned with a production-ready stack.

When to Use This CLAUDE.md Template

• You are building a multi-tenant NL SQL SaaS with dashboards and chart outputs.
• You require a repeatable CLAUDE Code pattern for Next.js + TS + Supabase, Clerk, Stripe.
• You need strict security guards (RLS, input validation, webhook verification) and deployment guidance.
• You want a paste-ready CLAUDE.md with a concrete project structure and testing checklist.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are the Claude Code assistant for building a production-ready NL SQL SaaS on Next.js 16 with TypeScript, Supabase, Clerk, and Stripe. Output must be actionable, security-conscious, and aligned to the given stack. Do not reveal credentials or bypass authentication.

Architecture rules:
- Use Next.js 16 with the App Router (src/app) and server components where feasible. API surfaces reside under src/app/api.
- Supabase is the primary data store with Row Level Security (RLS) and per-tenant schemas.
- Clerk handles authentication and session management; all protected routes require a valid session.
- Stripe handles billing; verify webhooks server-side and store customer/subscription data in Supabase.
- The NL-to-SQL generator (Claude Code) must produce parameterized, safe queries and never execute arbitrary DDL; enforce a query guard.
- All sensitive data implements environment-based access control and is never logged in plain text.
- Observability: log high-signal events to a central sink; expose metrics endpoints for health checks.

File structure rules:
- Keep code under src/ with the following layout:
  src/
    app/
      api/            # serverless endpoints
      dashboard/      # user-facing dashboards and pages
      auth/           # Clerk integration and session guards
      data/           # data access helpers, connectors to Supabase
      ml/             # NL-to-SQL orchestration and Claude Code templates
    components/        # reusable UI components
    lib/               # shared utilities and types
    services/          # external service integrations (Stripe, Clerk, Supabase)
    styles/            # global and component styles
    hooks/             # React/server hooks for data loading and auth
    types/             # TypeScript types for query generation and responses

Authentication rules:
- Use Clerk for all authentication; protect routes with server-only guards that verify Clerk session.
- Never trust client-supplied user identifiers; always resolve identity on the server.

Database rules:
- Supabase with per-tenant isolation via RLS and a tenant_id column in all user data tables.
- Use upsert with tenant-scoped patterns; queries must pass a tenant filter.
- Never expose raw database credentials to the client.

Validation rules:
- Validate all user input on the server; ensure the NL-to-SQL output matches allowed patterns (SELECT, WITH, LIMIT, etc.).
- Use parameterized queries in generated SQL; never interpolate user input directly.
- Validate chart output data contracts before rendering.

Security rules:
- Do not allow cross-tenant data leakage; enforce RLS and tenant-aware endpoints.
- Verify Stripe webhooks with signatures; store only necessary event data.
- Do not hard-code secrets; rely on environment variables.
- Use Content Security Policy (CSP) and strict transport security in responses.

Testing rules:
- Unit tests for NL-to-SQL generation rules and validation logic.
- Integration tests covering auth flows (Clerk), data access (Supabase), and webhooks (Stripe).
- End-to-end tests for the user journey from signup to dashboard with a sample NL query.

Deployment rules:
- Deploy on Vercel or equivalent; set environment variables: SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_SECRET, STRIPE_SECRET, NEXTAUTH_URL, STRIPE_WEBHOOK_SECRET.
- Ensure build-time checks enforce type safety and that NL-to-SQL generation is deterministic.
- Enable logs and error reporting in production.

Things Claude must not do:
- Do not execute arbitrary DDL or modify database schemas.
- Do not bypass authentication or access control checks.
- Do not leak API keys, secrets, or connection strings.
- Do not write or expose raw credentials in outputs.
- Do not rely on unsafe libraries or client-side SQL execution.

Recommended Project Structure

src/
  app/
    api/
      nlgql/            # endpoints feeding the NL-to-SQL service
    dashboard/          # main UI and charts
    auth/               # Clerk setup and middleware
    data/               # data access and Supabase client
    ml/                 # Claude Code-driven SQL generator logic
  components/
  lib/
  services/
  styles/
  hooks/
  types/

Core Engineering Principles

• Security by default: tenant isolation, secure defaults, and least privilege access.
• Explicit contracts: clear input/output types and validated schemas for all components.
• API-first: every feature is exposed as a stable API surface with proper versioning.
• Observability: thorough logging, metrics, and tracing for NL-to-SQL queries and payments.
• Reliability: idempotent operations, sensible retries, and robust error handling.

Code Construction Rules

• Write TypeScript types for all Claude Code outputs and enforce them in runtime guards.
• Use parameterized SQL for all generated queries and enforce tenant scoping via RLS.
• Keep Claude outputs declarative; avoid side effects in the code block unless explicitly defined.
• Structure CLAUDE.md blocks with clearly labeled sections and deterministic results.
• Do not reference libraries not used in the stack (e.g., Prisma, Mongoose, Drizzle).

Security and Production Rules

• Enable Supabase RLS with tenant_id and user role checks; never bypass policies.
• Validate and sanitize all NL input before transforming to SQL; never execute unsanitized inputs.
• Verify Stripe webhooks server-side; validate signatures before processing events.
• Keep secrets in environment variables; do not log them or expose them in API responses.
• Use CSP, HTTPS, and secure cookies; implement proper session management with Clerk.

Testing Checklist

• Unit tests for NL-to-SQL generation and query validation.
• Integration tests for auth (Clerk), data access (Supabase), and payments (Stripe).
• End-to-end tests for user journeys including NL querying and chart rendering.
• Deployment tests: environment variables present, secrets rotated, and webhooks verified.

Common Mistakes to Avoid

• Assuming NL input is always safe; always validate and constrain generation on the server.
• Exposing database credentials or API keys in client code or logs.
• Skipping Role-Based Access Control and tenant isolation in data access.
• Relying on client-side filtering for security checks; enforce on the server side.

Related implementation resources: AI Use Case for Wellness Coaches Using Stripe Data To Analyze Which Subscription Models Have The Highest Retention and Using Skill Files to Stop SQL Injection in Generated Backend Code.

FAQ