# 15 Real CLAUDE.md Files From Production SaaS Repos (What Actually Works)

> Annotated CLAUDE.md files for a Next.js + Stripe SaaS app, a Postgres/Drizzle schema, and a monorepo — plus a checklist for what to cut and when to split into a skill.

Canonical: https://www.agentickit.co/blog/claude-md-examples-production-saas
Last updated: 2026-10-29

**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](/skills) 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.

```markdown
# 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.

```markdown
## 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.

```markdown
# 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. -->
```

```markdown
# 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](/skills) 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](/tools/rules-grader) or convert between Cursor's `.mdc` rule format and Claude Code's CLAUDE.md with the [config converter](/tools/config-converter) — useful if you're supporting both ecosystems, as covered in [Cursor Rules vs Skills vs Commands vs Hooks](/blog/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](/blog/claude-code-hooks-examples) or the fuller [15-hook catalog](/blog/15-claude-code-hooks-examples) 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](/blog/claude-md-200-line-rule) 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](/blog/claude-md-rules-solo-saas-founders-2026) for a rule-writing method — pulling rules from actual corrections rather than a template — plus a copy-paste starting file.


## Related
- [rules-grader](https://www.agentickit.co/tools/rules-grader)
- [config-converter](https://www.agentickit.co/tools/config-converter)
- [code-reviewer](https://www.agentickit.co/agents/code-reviewer)
- [devops-engineer](https://www.agentickit.co/agents/devops-engineer)
- [project-conventions](https://www.agentickit.co/skills/project-conventions)
- [security-basics](https://www.agentickit.co/skills/security-basics)
- [/audit](https://www.agentickit.co/commands/audit)
