The CLAUDE.md File

What is CLAUDE.md?

CLAUDE.md is a markdown file at your project root that Claude Code reads automatically when you start a session. It's your project's "brain dump" for AI — everything the AI needs to know to write code that fits your codebase.

KitRocket ships with a pre-written CLAUDE.md that describes the full boilerplate. As you customize your project, you should update it to match.

What's in the default CLAUDE.md

The KitRocket CLAUDE.md includes these sections:

Project overview

# Project: KitRocket SaaS Boilerplate

A Next.js SaaS boilerplate with auth, payments, email, AI, and more.
Built for vibe coding with Claude Code.

Tech stack

## Tech Stack

- **Framework**: Next.js 15 (App Router, React 19)
- **Language**: TypeScript 5
- **Styling**: Tailwind CSS 4 + shadcn/ui
- **Database**: Supabase Postgres via Drizzle ORM
- **Auth**: Better Auth v1
- **Payments**: DodoPayments (Merchant of Record)
- **Email**: Resend + React Email
- **AI**: Anthropic Claude / OpenAI (Pro)
- **Analytics**: PostHog (Pro)
- **Blog**: MDX with next-mdx-remote (Pro)

Directory structure

## Directory Structure

src/app/          → Pages and API routes (App Router)
src/components/   → React components by domain
src/lib/          → Business logic and services
src/db/           → Database schema and migrations
content/blog/     → MDX blog posts
prompts/          → Prompt Recipes for AI development

Conventions

## Conventions

- Server components by default, "use client" only when needed
- Path alias: @/ maps to src/
- Immutable data patterns — never mutate objects
- Validate inputs at system boundaries with zod
- Handle errors explicitly — never swallow errors
- Small functions (<50 lines), small files (<400 lines)

Key files

## Key Files

- src/lib/auth/server.ts — Better Auth configuration
- src/lib/auth/client.ts — Auth client and hooks
- src/lib/payments/plans.ts — Subscription plan definitions
- src/lib/payments/checkout.ts — Checkout session creation
- src/lib/payments/webhook.ts — Webhook event processing
- src/db/schema/ — All database table definitions
- src/lib/email/send.ts — Email sending functions
- src/lib/email/templates/ — React Email templates

Database schema

## Database Schema

users: id, email, name, avatar, createdAt
sessions: id, userId, token, expiresAt
accounts: id, userId, provider, providerAccountId
subscriptions: id, userId, plan, status, dodoCustomerId, dodoSubscriptionId
usage: id, userId, tokensUsed, model, createdAt (Pro)

API routes

## API Routes

POST /api/auth/*           → Better Auth (all auth flows)
POST /api/checkout          → Create checkout session
POST /api/webhook/dodo      → DodoPayments webhooks
POST /api/ai/chat           → AI chat (Pro, streaming)
GET  /api/user/profile      → Get user profile
PATCH /api/user/profile     → Update user profile

How to customize

As your project evolves, update CLAUDE.md to reflect reality:

After adding a feature

## New: Team System

Tables: teams, team_members
Routes: GET/POST /api/teams, POST /api/teams/invite
Key files: src/lib/teams/service.ts, src/db/schema/teams.ts

After changing the database

Update the schema section to match your current tables and columns.

After adding conventions

## Conventions (updated)

- All API routes return { data, error } envelope
- Use React Query for client-side data fetching
- Team-scoped queries always check membership first

After switching a service

If you migrated from DodoPayments to Stripe, update the tech stack and key files sections.

Best practices

Keep it accurate

An outdated CLAUDE.md is worse than none at all. If Claude follows stale conventions, it generates code that doesn't fit.

Be specific

# Vague — Claude has to guess
Use proper error handling.

# Specific — Claude knows exactly what to do
Return errors as { data: null, error: "Human-readable message" } with
appropriate HTTP status codes. Log the full error server-side with context.
Never expose internal error details to the client.

Include examples

## API Route Pattern

Every API route follows this structure:

1. Check authentication
2. Validate input with zod
3. Call service function
4. Return response

Example: src/app/api/checkout/route.ts

Don't overload it

Keep CLAUDE.md under 500 lines. If it gets too long, Claude spends context window reading it instead of solving your problem. Focus on what's unique about your project.

Update it with Claude

claude "Read the current state of the project and update CLAUDE.md to match.
Keep the same structure but update any outdated information."

CLAUDE.md vs .cursorrules

Both serve the same purpose — project context for AI. The difference is the consumer:

File	Used by	Format
CLAUDE.md	Claude Code	Markdown (flexible)
.cursorrules	Cursor IDE	Markdown (with Cursor-specific conventions)

KitRocket ships with both, pre-configured. If you update one, update the other to stay in sync.

Next steps

• Claude Code Setup — get started with Claude Code
• Tips — maximize your productivity