← Back to Guides · CLAUDE CODE
15 Real CLAUDE.md Files From Production SaaS Repos (What Actually Works)
Short answer: A CLAUDE.md file works when it tells Claude Code things it can't figure out by reading the code — where the schema lives, which commands are safe to run, what pattern this specific repo uses for errors or auth — not when it restates generic advice like "write clean code" or "use TypeScript." Below are three annotated CLAUDE.md files, one per stack (Next.js + Stripe SaaS, Postgres/Drizzle, and a monorepo with per-package files), with line-by-line notes on why each line earns its place, plus a checklist for what to cut.
Every "CLAUDE.md best practices" result right now is a tips list: keep it short, use markdown headers, don't repeat the README. True, and useless without something to copy. This post skips the tips and gives you the files.
Why most CLAUDE.md files fail: too generic or too long
There are two failure modes, and they look like opposites but come from the same root cause: the file was written by guessing what a CLAUDE.md "should" contain instead of by asking what Claude actually got wrong last week.
Too generic. Lines like "write clean, maintainable code" or "follow best practices" cost context-window space and teach the model nothing — it already defaults to clean code. A line only earns its place if removing it would change Claude's behavior. "Use pnpm, never npm" changes behavior (wrong lockfile otherwise). "Write good code" doesn't.
Too long. CLAUDE.md loads into every single session's context, every time. A 400-line file isn't more thorough, it's more expensive — and past a certain length, the model starts treating all of it as equally skimmable, which means the one load-bearing line (the migration command, the auth invariant) gets the same attention as the filler around it. Shorter files with only load-bearing lines get followed more reliably, not less.
The fix for both is the same test: for every line, ask "what would Claude do wrong without this line?" If you can't answer concretely, cut it. If the answer is "it would guess a plausible but wrong file path / command / pattern," keep it.
That test is also the splitting rule. If a block of instructions only applies to one task (e.g., "when adding a Stripe webhook, do X, Y, Z") rather than every session, it usually belongs in a skill invoked on demand, not in CLAUDE.md, where it burns tokens on every unrelated session too. More on that in the checklist at the end.
Annotated example: Next.js App Router + Stripe SaaS
This is the shape you want for a single-repo SaaS app with billing. Every line is commented with why immediately after.
# CLAUDE.md
## Stack
Next.js 15 App Router, TypeScript strict, Tailwind, Stripe, Postgres via Drizzle, deployed on Vercel.
<!-- Names the exact versions/tools so Claude doesn't guess Pages Router patterns or a different ORM's syntax. -->
## Commands
- Dev: `pnpm dev`
- Test: `pnpm test` (Vitest, not Jest)
- Typecheck before any commit: `pnpm typecheck`
- DB migration: `pnpm db:generate && pnpm db:migrate` — never edit `drizzle/*.sql` by hand
<!-- "Never edit migration files by hand" prevents a specific real failure: hand-edited migrations drift from the Drizzle schema and break `db:generate` next time. -->
## Billing
- Stripe webhook handler: `app/api/webhooks/stripe/route.ts`. Always verify `stripe-signature` before parsing the body — see existing handler for the exact pattern.
- Plan limits live in `lib/plans.ts`, not hardcoded in route handlers.
- Never log full Stripe event payloads — they contain customer PII. Log `event.type` and `event.id` only.
<!-- This is the one section that's genuinely dangerous to get wrong (unverified webhooks, PII in logs) and not obvious from reading one file in isolation. -->
## Auth
- Session checks happen in `middleware.ts`, not per-route. If you're adding a new protected route under `app/(dashboard)`, it's already covered — don't add a redundant check.
<!-- Prevents Claude from re-implementing auth checks it thinks are missing, a very common false positive. -->
## Patterns to follow
- Server Actions for mutations, Route Handlers only for webhooks/external callbacks.
- Errors: throw `AppError` (see `lib/errors.ts`), never bare `Error` — the error boundary matches on `AppError.code`.
<!-- Encodes a project-specific convention that has no single obviously-correct default; without this line Claude would throw plain Errors and the error boundary wouldn't catch them cleanly. -->
## Do not touch
- `lib/stripe-webhook-secret.ts` is intentionally untyped as `any` — don't "fix" it, it's a workaround for a Stripe SDK type bug. See comment in file.
<!-- Stops a well-intentioned refactor from reverting a deliberate workaround. This is the single highest-value kind of line in any CLAUDE.md: it's not teaching a pattern, it's preventing a regression. -->
Notice what's not there: no "write tests for new features" (the testing-vitest convention plus CI catches this), no "use semantic commit messages" (that's a .gitmessage template's job, not context burned every session), no explanation of what Next.js App Router is (Claude knows).
Annotated example: Postgres/Drizzle schema-pointer pattern
For apps with a non-trivial schema, the highest-leverage CLAUDE.md content isn't a description of the schema — it's a pointer to where the schema truly lives, plus the one or two invariants that aren't visible from the schema file alone.
## Database
- Schema source of truth: `db/schema.ts`. Read it before writing any query — do not assume column names from memory of a previous session.
<!-- "Read it before writing any query" is the load-bearing instruction. Without it, Claude will sometimes pattern-match a column name from a similar SaaS schema it's seen elsewhere instead of this repo's actual one. -->
- Soft deletes: every table has `deletedAt`. All reads must filter `deletedAt IS NULL` — there's no DB-level view enforcing this, it's convention only.
<!-- This is the single most common bug in Drizzle/Prisma SaaS repos: a new query forgets the soft-delete filter and resurrects "deleted" rows. It's invisible in the schema file itself (deletedAt just looks like a timestamp column), so it has to live in CLAUDE.md. -->
- Multi-tenant: every tenant-scoped table has `orgId`. Every query must filter by `orgId` from the session — there is no RLS, isolation is enforced in application code only.
<!-- This is the line that prevents a cross-tenant data leak. It's the highest-severity thing a CLAUDE.md can communicate in a multi-tenant app, and it's exactly the kind of invariant that isn't derivable from reading the schema. -->
- Migrations: `pnpm db:generate` after any schema.ts change, commit the generated SQL. Never run migrations directly against production from a local shell.
<!-- Operational guardrail: prevents an agent from "helpfully" running a migration against a prod DATABASE_URL it finds in .env. -->
The pattern here: don't paste the schema (it goes stale and duplicates schema.ts), point at it, then add the two or three invariants that a fresh read of the schema file wouldn't surface — soft deletes and tenant isolation are the classic examples because they're encoded as plain columns with no type-level enforcement.
Annotated example: monorepo with per-package CLAUDE.md
In a Turborepo/pnpm monorepo, a single root CLAUDE.md either gets too generic to be useful for any one package, or too long because it tries to cover all of them. The fix is a short root file plus one file per package that only Claude sessions working inside that package load.
# root CLAUDE.md
## Structure
- `apps/web` — the customer-facing Next.js app
- `apps/api` — standalone Fastify API, deployed separately
- `packages/db` — Drizzle schema + migrations, shared by both apps
- `packages/ui` — shared React components, no app-specific logic allowed here
<!-- Orients Claude to where things live before it starts searching — cheap, load-bearing for a repo this size. -->
## Cross-package rules
- Never import from `apps/*` into `packages/*` — dependencies flow one direction only.
- Shared types go in `packages/types`, not duplicated per app.
<!-- These are rules that only make sense at the monorepo level and would be redundant if repeated in every package file. -->
# apps/api/CLAUDE.md
## This package
Fastify API, deployed to Fly.io independently from apps/web. Do not assume Next.js conventions here — no Server Actions, no `app/` directory.
<!-- Explicitly rules out patterns Claude might import by habit from the other app in the same repo, which is the main failure mode unique to monorepos. -->
## Auth
Validates the same JWT apps/web issues, but via a shared `packages/auth` verify function — don't reimplement verification here.
The per-package files stay short because they only need to say what's different about this package, not restate the whole stack — the root file already covers the shared stack and cross-cutting rules once.
Checklist: what to cut, what to keep, when to split into a skill instead
| Keep in CLAUDE.md | Cut from CLAUDE.md | Move to a skill instead |
|---|---|---|
Exact commands (test, migrate, typecheck) that aren't in package.json scripts a reader would find | "Write clean, readable code" and similar generic advice | Multi-step procedures used occasionally ("when adding a Stripe webhook, do steps 1-6") |
| Invariants with no type-level enforcement (soft deletes, tenant isolation, PII logging rules) | A restated README or architecture diagram | Task-specific checklists (SEO audit steps, a release checklist) |
| "Do not touch" notes on deliberate workarounds | Explanations of frameworks/libraries the model already knows | Anything only relevant to <20% of sessions in this repo |
| Pointers to source-of-truth files (schema, plan limits) | Full schema or API contract pasted inline (goes stale) | Long reference material (full API docs, design system tokens) |
| Cross-package rules unique to a monorepo's dependency direction | Per-package detail that belongs in that package's own file | — |
The dividing line: CLAUDE.md is for things true on every session in this repo (or this package); a skill is for things true only on some sessions, invoked when that task comes up. Loading a six-step webhook checklist into context on a session that's just fixing a CSS bug is the same mistake as loading generic advice — context spent on something this session doesn't need.
If you want a second opinion on an existing file rather than writing one from scratch, run it through the rules grader or convert between Cursor's .mdc rule format and Claude Code's CLAUDE.md with the config converter — useful if you're supporting both ecosystems, as covered in Cursor Rules vs Skills vs Commands vs Hooks.
For the hooks that enforce some of these invariants automatically instead of relying on Claude reading a line correctly every time — blocking a hand-edited migration file, or a git commit that includes a .env — see Claude Code Hooks for Founders or the fuller 15-hook catalog covering commit guardrails and usage tracking too.
FAQ
How long should a CLAUDE.md file be? There's no fixed number — the right length is "every line changes Claude's behavior from what it would otherwise do." For a single-app SaaS repo, that's usually 40-80 lines across commands, stack, and a handful of invariants. A monorepo root file can be shorter than that if per-package files carry the package-specific detail. See the 200-line rule, explained for where that often-cited number actually comes from and why the deletion test matters more than the count.
Should CLAUDE.md include the database schema? Point at the schema file (db/schema.ts, prisma/schema.prisma) instead of pasting it. A pasted schema goes stale the moment someone adds a column and forgets to update CLAUDE.md, which is worse than not documenting it at all — Claude will trust the stale copy over the real file.
What's the difference between CLAUDE.md and a skill for this kind of content? CLAUDE.md loads into every session automatically; a skill loads only when invoked for a matching task. Content needed every session (stack, commands, cross-cutting invariants) belongs in CLAUDE.md. Content needed only for specific recurring tasks (a release checklist, an SEO audit, a webhook-adding procedure) belongs in a skill, so it doesn't cost context on unrelated sessions.
Can a monorepo have more than one CLAUDE.md file? Yes — Claude Code reads CLAUDE.md files up the directory tree from wherever a session starts, so a root file plus one per package (e.g., apps/api/CLAUDE.md) is a supported and common pattern, not a workaround.
Do I need a CLAUDE.md if my project is small? Probably still worth a short one for commands and any non-obvious invariant, but skip the stack/structure sections if the repo is small enough that ls answers those questions as fast as reading a file would.
How do I turn what I learn from these examples into rules for my own repo? See 15 CLAUDE.md Rules Solo SaaS Founders Actually Need in 2026 for a rule-writing method — pulling rules from actual corrections rather than a template — plus a copy-paste starting file.
Related Tools & Agents
Grade the CLAUDE.md you already have
Paste your file in and see which lines are load-bearing and which are generic filler.
Open the rules grader →