CLAUDE.md Template for Next.js + TS + Supabase + Clerk + Stripe + OpenAI Agents SDK

Overview

This CLAUDE.md Template describes a production-ready blueprint for a complete AI Agent Builder SaaS built on Next.js with TypeScript, backed by Supabase for data and auth, Clerk for user-facing authentication flows, Stripe for billing, and OpenAI Agents SDK with tool calling. It includes a copyable CLAUDE.md block and stack-aligned project structure, security requirements, testing guidance, and deployment considerations. Direct answer: paste the CLAUDE.md block into your repository to bootstrap the project structure and governance for a multi-tenant AI agent marketplace and builder.

When to Use This CLAUDE.md Template

• You are building a SaaS that enables users to create, deploy, and share AI agents via public links.
• You want a single-codebase pattern with Next.js App Router, TypeScript, and a Postgres-backed data layer via Supabase.
• You require robust authentication with Clerk and a separate, secure user session on server routes.
• You plan to monetize with Stripe and manage subscriptions, invoices, and webhooks.
• You need OpenAI Agents SDK integration for agent orchestration, tool calling, and multi-agent workflows.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role:
- You are Claude Code, an AI assistant tasked with delivering production-ready, stack-specific guidance and a copyable CLAUDE.md template for building a complete AI Agent Builder SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, and OpenAI Agents SDK. You should produce concrete code blocks, architecture decisions, and validation criteria that engineers can paste directly into their repositories.

Architecture rules:
- Use Next.js with App Router (server components where applicable) and TypeScript throughout.
- Centralize business logic in /src/services and /src/lib; keep pages/components lean.
- Supabase is the primary database and auth provider; use Row Level Security with policies.
- Clerk handles user-facing authentication flows; server-side must validate Clerk sessions for sensitive endpoints.
- Stripe handles billing; use webhooks secure with Stripe-signed secrets. Do not rely on client-side billing logic for sensitive operations.
- OpenAI Agents SDK provides agent orchestration and tool calls; wrap calls in a service layer and honor rate limits and timeouts.
- Public agent links must be shareable without exposing server secrets; enforce access control on protected resources.
- Do not hardcode secrets in client code; fetch secrets from environment variables and secret managers at runtime.
- Prefer server actions and API route handlers for all sensitive operations.

File structure rules:
- Create a Next.js project under apps/web with /src containing:
  - /app for App Router pages
  - /components for reusable UI components
  - /hooks for React hooks
  - /lib for shared utilities
  - /services for business logic
  - /types for TypeScript types
  - /styles for global styles
  - /server to house route handlers and middleware
  - /db to hold migrations and seed data (no Prisma)
- Include a dedicated /db/migrations directory for Supabase migrations.
- Include a /scripts directory for dev and CI tooling.
- Add .env.example at repo root; never commit secrets.

Authentication rules:
- Use Clerk for user-facing auth flows (sign in/up, sessions) on the client.
- Verify Clerk session on all server routes that access user data.
- Sync relevant user metadata to Supabase if needed for tenant assignment or roles.
- Do not expose JWTs or API keys to the client.

Database rules:
- Use Supabase Postgres with Row Level Security enabled.
- Implement policies for read/write access per tenant and per resource.
- Store agent definitions, user accounts, and public links in separate tables with proper foreign keys.
- Encrypt sensitive data at rest where appropriate; use environment-managed encryption for secrets.

Validation rules:
- Use Zod for all input validation; fail fast with explicit error messages.
- Normalize and sanitize all inputs server-side before persistence.

Security rules:
- Do not log secrets or API keys in logs.
- Enable HTTPS, CSP, and secure cookies in production.
- Validate all webhook payloads (Stripe, OpenAI) using signature verification.
- Guard API routes with middleware that checks authentication and authorization.
- Apply rate limiting on endpoints that trigger OpenAI calls to avoid abuse.

Testing rules:
- Unit tests for utilities and data transformers.
- Integration tests for API routes and auth flows (Clerk + Supabase).
- E2E tests for agent creation, sharing, and basic tool calls using a headless browser.
- Use mocks for external OpenAI API calls in unit tests; use real endpoints in integration tests only behind CI with secrets.

Deployment rules:
- Deploy to a hosting platform like Vercel or equivalent; ensure environment variables are set in production.
- Run database migrations in CI or during deploy as appropriate for your hosting provider.
- Enable preview deployments for feature branches to test agent sharing and public links before release.

Things Claude must not do:
- Do not reveal secret keys or credentials.
- Do not bypass authentication or authorization checks.
- Do not generate or expose real Stripe webhook signing secrets in code or docs.
- Do not call real OpenAI endpoints in unit tests without proper mocks.
- Do not propose unsafe filesystem or network access that violates tenant isolation.

Recommended Project Structure

project-root/
  apps/
    web/                 # Next.js app (multi-tenant SaaS)
      src/
        app/             # App Router routes and server components
        components/
        hooks/
        lib/
        services/
        types/
        styles/
      next.config.js
      tsconfig.json
      package.json
      .env.local.example
  db/
    migrations/
    seeds/
  scripts/
  README.md

Core Engineering Principles

• Single responsibility and clear boundaries between UI, domain logic, and data access.
• Type safety and design-by-contract via TypeScript and Zod validations.
• Security by default: least privilege, server-side validation, and secret management.
• Tenant isolation and robust access controls for multi-tenant SaaS.
• Observability: structured logging, metrics, and error reporting for production reliability.

Code Construction Rules

• Use Next.js App Router with server components where appropriate; keep client payload small.
• Encapsulate OpenAI interactions behind a service layer; batch tool calls and handle timeouts.
• Store user and tenant data in Supabase with proper RLS policies; never rely on client-side checks for authorization.
• All external secrets must live in environment variables or secret managers; never commit them.
• Input validation with Zod on every API boundary; normalize data before persistence.
• Follow a consistent naming convention for directories and files; enforce lint rules and type checks in CI.

Security and Production Rules

• Enable HTTPS, secure cookies, and CSP on all production deployments.
• Stripe webhooks must be validated with signed payloads; process via server-side endpoints only.
• OpenAI API keys and endpoints must be accessed from server-side code; never in the browser.
• Implement robust error handling and user-facing error messages; avoid leaking internal errors.
• Limit tool calls and OpenAI usage with quotas and rate limits to prevent abuse.

Testing Checklist

• Unit tests for utilities, validators, and adapters (use Vitest or Jest).
• Integration tests for API routes, Stripe webhooks, and Clerk auth flows.
• End-to-end tests for agent creation, public link sharing, and a simple tool call workflow.
• CI checks: type safety, linting, and test suite; run migrations in CI when applicable.

Common Mistakes to Avoid

• Assuming client-side is trusted for auth or billing decisions.
• Exposing API keys or secrets in the frontend bundle or repo.
• Failing to implement proper Row Level Security for multi-tenant data.
• Overusing real OpenAI calls in tests without mocks or sandbox keys.
• Ignoring Stripe webhook verification or failing to handle retries.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and CLAUDE.md as Project Memory: Practical AI Development Workflows and Templates.

FAQ

• What is this CLAUDE.md Template for? It provides a copyable CLAUDE.md block and stack-specific guidance to build a complete AI Agent Builder SaaS with Next.js, TS, Supabase, Clerk, Stripe, and OpenAI Agents SDK.
• Can I reuse the template for other stacks? The template is tailored to the Next.js + TS + Supabase + Clerk + Stripe + OpenAI Agents SDK stack; adapt file structure and service interfaces for other stacks.
• How do I share a public agent? Implement a public link that references an agent resource with an opaque token or slug; ensure read access is restricted and audit logs are kept for sharing.
• How do I test tool calling? Mock OpenAI tool calls in unit tests; use integration tests to verify end-to-end tool invocation behavior with real API keys in a controlled environment.
• What deployment targets are recommended? Vercel or similar modern hosting with support for Next.js App Router; ensure CI runs migrations and secrets are injected via environment variables.