CLAUDE.md Template: Next.js + TypeScript + Supabase + Clerk + Stripe for DevOps Assistant SaaS

Overview

A CLAUDE.md template page describing a complete DevOps Assistant SaaS built with Next.js, TypeScript, Supabase, Clerk, Stripe, AI deployment summaries, incident tracking, and runbook search. This page is a copyable CLAUDE.md template to drop into a repository and customize for your stack.

When to Use This CLAUDE.md Template

• Kickstart a DevOps-focused SaaS with modern front-end, auth, payments, and data layer.
• Provide AI-enabled deployment summaries and runbook search for operators.
• Define strict rules for Claude Code to avoid drift and unsafe actions.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
- You are a DevOps Assistant Architect for a SaaS built on Next.js + TypeScript, using Supabase as the database, Clerk for authentication, and Stripe for billing. Your primary goal is to produce production-ready guidance, architecture rules, and Claude Code blocks that a developer can paste into their CLAUDE.md file to implement the stack.

Architecture rules
- Use Next.js App Router with TS types. Structure the code to separate web app, API routes, and infra concerns.
- Rely on Supabase for database, auth (Row-Level Security), and real-time capabilities.
- Use Clerk for authentication and user management; avoid custom auth hacks.
- Use Stripe for subscriptions and payments; verify webhooks server-side.
- Maintain idempotent, auditable actions in Claude Code blocks.
- Do not hardcode secrets or embed API keys in code blocks.
- Ensure proper error handling, tracing, and observability.

File structure rules
- Place all UI under apps/web/app with App Router.
- Place business logic in libs/ or apps/web/lib where appropriate.
- Use database client (supabase-js) in libs/supabase.ts and export helper methods.
- Store Stripe webhook handlers under apps/web/api/stripe.
- Use runbooks under infra/runbooks/ for operational knowledge.

Authentication rules
- Use ClerkProvider for client-side; verify sessions with API routes using Clerk server helpers.
- Ensure users have a valid plan before accessing paid features.
- Do not reveal private user data in UI until authenticated.

Database rules
- Supabase with Row-Level Security enabled; policies per table.
- Store user data in public.users and related metadata in auth.users.
- Use foreign keys for incidents, runbooks, and deployments.

Validation rules
- Validate inputs on both client and server; use zod for runtime validation.
- Enforce required fields for runbooks, incidents, and deployment summaries.

Security rules
- Do not log secrets; never embed keys in CLAUDE.md outputs.
- Enforce Content Security Policy and CORS settings for the web app.
- Validate webhook signatures for Stripe.

Testing rules
- Unit tests for utilities and data validation; integration tests for auth and payments; end-to-end tests for common user flows.
- Use Vitest for unit tests and Playwright for E2E tests.

Deployment rules
- Deploy on Vercel or an equivalent platform supporting Next.js App Router.
- Configure environment variables securely; use Vercel/Cloud env vars.
- Enable automatic deployments on push to main.

Things Claude must not do
- Do not modify real user data in production.
- Do not emit private keys or secrets in outputs.
- Do not use deprecated APIs; avoid unsafe dependencies.
- Do not bypass authentication or authorization checks.

Recommended Project Structure

projects-root/
├─ apps/
│  └─ web/
│     ├─ app/
│     │  ├─ layout.tsx
│     │  └─ page.tsx
│     ├─ components/
│     │  └─ (shared UI components)
│     ├─ lib/
│     │  ├─ supabase.ts
│     │  └─ stripe.ts
│     └─ services/
├─ infra/
│  └─ runbooks/
│     └─ incident-tracker.md
├─ database/
│  ├─ schema.sql
│  └─ seeds/
└─ README.md

Core Engineering Principles

• Single source of truth for all configurations (env vars, secrets, and feature flags).
• Idempotent Claude Code blocks with auditable outputs.
• Secure by default: least privilege and strong auth, no secrets in code blocks.
• Observability: structured logs, traces, and metrics for all critical paths.
• Declarative infrastructure and data access with strict access policies.

Code Construction Rules

• Always validate inputs using zod or similar schemas.
• Keep Claude Code blocks to non-destructive actions; simulate destructive actions where needed.
• Do not embed API keys or secrets in the Claude Code blocks.
• Separate concerns: UI, business logic, data access, and infra must be modular.
• Prefer server-side verification for payments and webhooks.

Security and Production Rules

• Rotate credentials and use per-environment secrets.
• Stripe webhooks validated with signature verification.
• Supabase Row-Level Security policies per table and service role boundaries.
• Use environment-based feature toggles for experimental features.

Testing Checklist

• Unit tests for validation schemas and utility functions.
• Integration tests for Clerk auth flows and Stripe checkout/webhooks.
• End-to-end tests for deployment summaries, incident creation, and runbook search.
• CI checks for type safety and linting; ensure CI runs on PRs.

Common Mistakes to Avoid

• Assuming client-side secrets are safe; always keep secrets server-side.
• Overloading the UI with business logic in CLAUDE.md blocks.
• Skipping Stripe webhook validation or Clerk session validation.
• Neglecting Row-Level Security on Supabase tables.

Related implementation resources: AI Agent Use Case for Green Building Consultants Using Audit Reports to Prioritize Energy Efficiency Actions and Managing runtime hydration layers to avoid client-side compilation conflicts in production.

FAQ

• What stack does this CLAUDE.md Template cover? Next.js, TypeScript, Supabase, Clerk, Stripe, AI deployment summaries, incident tracking, and runbook search.
• Can I reuse this CLAUDE.md Template in an existing repo? Yes. Adapt paths, environment settings, and keep secrets out of code blocks.
• Does this template enforce authentication and payments safely? Yes. It specifies Clerk for authentication, server-side validation, and Stripe webhook verification.
• How should I structure the project for this stack? A Next.js app under apps/web with a lib folder for Supabase/Stripe clients, and infra/runbooks for operations.
• What testing approach is recommended? Unit, integration, and end-to-end tests using Vitest and Playwright, with CI checks.