Production-Ready CLAUDE.md for Next.js 15 + SQLite SaaS

A comprehensive, opinionated CLAUDE.md template that tells Claude (and any LLM) how to write code for a typical SaaS product built with Next.js 15 App Router and SQLite.

What is CLAUDE.md?

CLAUDE.md is a project-level instruction file that Claude Code reads automatically when working in your repository. It acts as a senior engineer's onboarding doc — covering architecture, conventions, commands, and patterns so that AI-generated code matches the rest of your codebase.

What's covered

• Project structure — Where files go and why
• Commands — Dev, build, test, lint, migrate
• Code style — TypeScript strictness, naming, imports
• Component patterns — Server vs Client components, UI primitives
• Database conventions — SQLite with better-sqlite3 (dev) and Turso (prod), Drizzle ORM, migrations, pragmas
• Auth patterns — Session-based auth with Lucia, protecting routes and actions
• API routes & Server Actions — When to use which, input validation with Zod
• Error handling — Error hierarchy, API errors, error boundaries
• Testing — Unit (Vitest), integration (real SQLite), E2E (Playwright)
• Environment variables — Validation with Zod, what to expose to the client
• Deployment — Vercel, Docker, SQLite in serverless

Quick start

Option 1: Copy directly

cp CLAUDE.md /path/to/your/project/CLAUDE.md

Open it, search-replace anything project-specific, and you're done.

Option 2: Use the generator script

./generate-claude-md.sh --name "My SaaS App" --output /path/to/your/project/CLAUDE.md

The script replaces the generic project name and copies the file to your project.

Customizing

This template is opinionated by design. You should adjust it to match your actual stack:

• Different ORM? Replace the Drizzle sections with Prisma/Kysely equivalents.
• Different auth? Swap Lucia references for NextAuth.js, Clerk, etc.
• Different DB? The SQLite-specific sections (pragmas, WAL mode, Turso) are clearly marked.
• Different styling? Replace Tailwind references with your CSS approach.

The structure and conventions (error handling, testing philosophy, component patterns) transfer across most stacks.

Philosophy

This CLAUDE.md was written with these principles:

1. Opinionated > comprehensive. Tell the AI exactly what to do, not every option.
2. Show, don't just tell. Every convention includes a code example.
3. Cover the pitfalls. The "Common pitfalls" section prevents the bugs that waste the most time.
4. Production-first. Conventions that work in a real product with real users, not a tutorial.

License

MIT — use it however you want.