DEV Community: Dan

Your CLAUDE.md should encode invariants, not a map of where files live

Dan — Mon, 08 Jun 2026 12:39:33 +0000

Most CLAUDE.md files I see are a folder map and a naming convention. That is close to the least valuable thing you can hand an agent, because it already infers structure from the repo. What it cannot infer are the rules that must never break, and the reasons behind them.

An agent will happily write code that compiles, passes types, and quietly violates a security or data invariant. A file map does nothing to stop that. A list of invariants with reasons does.

Here is the shape that has worked for me on Next.js + SQLite SaaS projects.

Encode invariants, with the reason

Not "put queries in lib/db." Instead:

All writes go through a server action or route handler, and auth is checked there. The client is untrusted; the server is the only enforceable boundary.
Every user-owned query includes an ownership predicate. SQLite has no row-level security, so this one line is the only thing stopping cross-tenant reads. Forgetting it is a silent data leak, not an error the agent will ever see.
Never grant access or money state from a success URL, only from a verified server event.

The "and the reason" part matters. Claude follows a rule it understands far more reliably than one it takes on faith.

The SQLite gotcha worth stating outright (I normally run Postgres)

I build on Postgres, where row-level security is a backstop: even if a query forgets its ownership filter, RLS can stop the cross-tenant read. SQLite has none. So on SQLite, "an ownership predicate on every user-scoped query" is not style advice, it is your entire multi-tenant boundary. If it is not stated as an invariant in the CLAUDE.md, an agent will eventually write a query without it and nothing will complain. (On Postgres, keep the predicate and keep RLS. Belt and suspenders.)

Tell it how to work, not just what to build

Invariants describe the destination. They do not stop the agent getting there in one giant, unreviewable leap. So the other half of a good CLAUDE.md is the working method.

Mine is phase-gated micro-stepping, and the key move is that the agent does not authorise its own progress:

Work runs in phases (scope, build, verify, review, fix, ship) with a human checkpoint between each. The agent stops at every boundary, reports, and waits for an explicit go phrase. "looks good" does not advance it.
The build phase is itself micro-stepped: one section at a time, with a typecheck, test, and pitfall scan after each, then a commit and a stop.
A circuit breaker: if it cannot get a check green in about five tries, it stops and reports instead of looping forever.
Defensive commits before multi-file changes, full implementations only (no // TODO stubs), and a tight state-summary handoff so a fresh session resumes without re-reading the repo.

A broken invariant shows up immediately in a small gated step; a big autonomous diff buries it. This is the part of a CLAUDE.md almost nobody writes, and it is the part that most changes how the agent behaves.

Add a "danger paths to test" section

The highest-leverage block. These are the flows that cost you money or data when they break, and the ones agents skip because they are boring:

signup / login / logout
protected route redirect when unauthenticated
CRUD authorization (user A cannot touch user B's rows)
migration on a fresh database
migration on an existing database
seed command run twice (no duplicates)
production build
first run after clone with only .env.example

Ending the file with "before you call this done, prove these still pass" turns the agent from a confident code generator into something closer to a careful engineer.

The full file

Complete, opinionated CLAUDE.md for a Next.js + SQLite SaaS (Drizzle, server actions, the Next 16 caching rules, security baseline, the micro-stepping method, anti-patterns with reasons, and the danger-paths checklist). https://gist.github.com/HalbonLabs/485186f4b2846bb1d13d2240651df21d

I build production Next.js templates for a living (Template Empire), so I think about this as "what stops a buyer's first clone from breaking," which turns out to be the same question as "what should the agent never get wrong." The deeper standards behind it are public: templateempire.io/standards

What invariants are in your CLAUDE.md that you would not ship without?

Most Next.js SaaS boilerplates ship you a landing page, not a product

Dan — Mon, 08 Jun 2026 07:49:12 +0000

I have bought a lot of Next.js SaaS boilerplates. Most have the same problem: the demo looks incredible, and the repo behind it is held together with tape.

You see a stunning landing page, a pricing section, a dashboard screenshot. You pay. You clone it. An hour in you find auth with no session-refresh handling, a Stripe webhook that never verifies signatures, no tests, accessibility never considered, and "compliance" that means a Terms page someone pasted in.

The landing page sells. The product underneath is the 80% nobody screenshots.

What's actually missing

The hard, not so glamorous parts are exactly the parts a screenshot can't show:

Auth that survives reality: session refresh, RBAC, httpOnly cookies, the logout-everywhere case.
Billing that won't lose money: Stripe webhook signature verification, idempotency, the failed-payment and proration paths.
Data safety: row-level isolation so tenant A never sees tenant B, parameterised queries, an audit trail.
Compliance plumbing: a real data-export/DSAR flow, account deletion, cookie consent that honours Reject-All and GPC, not just legal pages.
The boring guarantees: TypeScript strict with zero any, real test coverage, WCAG AA, a build that actually passes CI.

None of that photographs well. All of it is what breaks at 2am once you have real users.

The thing you can't see is the thing you're buying

When you buy a template, you are wiring your business onto a stranger's code with no evidence it is safe. You are trusting a screenshot. That is backwards.

So when I built Template Empire, I made the verification the product, not the marketing. Every release runs through:

Deterministic gates that don't care about opinions: typecheck, lint, full test suite, OWASP scan, a four-run Lighthouse matrix, Docker health check, dependency licence audit. Any gate fails, it does not ship.
A multi-model review panel: 13 Claude specialists plus OpenAI Codex and Google Gemini, each reviewing from a different angle. Different models catch different blind spots. A finding raised by two or more auto-blocks at P0/P1.
A buyer simulation: extract the ZIP, read the README, cp .env.example .env with zero manual edits, install, seed, log in, run. If the path a buyer takes breaks, it does not ship. That one dumb script has caught issues no code review did.
A signed Quality Gate Report PDF in every download, so you can see exactly what was checked.

The receipts so far: 8,000+ automated tests, 1000+ issues found and fixed, 800+ pitfall patterns prevented, 0 P0/P1/P2 issues at release sign-off.

What to audit before you buy ANY boilerplate

You do not have to buy mine. But before you trust any paid starter with your business, check these:

Does the Stripe webhook handler verify the signature? Grep for it. If it's missing, walk away.
Is there real multi-tenant isolation, or just a userId column and hope?
Are there actual tests, or one token test file for the screenshot?
Is auth using httpOnly cookies, or is a token sitting in localStorage?
Is there a data-export and account-deletion path? You will need it for GDPR/CCPA.
TypeScript strict with no any, or any everywhere once you open the files?
Is there any evidence of QA at all, a report, a changelog, a versioned release history? Or just a v0.1.0 zip?

If a seller can't answer those, the landing page was the product.

What I learned building the pipeline

Two things. The AI reviewers are excellent at surfacing candidate issues and useless as a single source of truth: they only earn their keep paired with deterministic checks and a cross-confirmation rule. And the highest-value test in the whole system is the dumbest one, install it like a customer and see if it runs.

The full process is public if you want to pick it apart: templateempire.io/standards. And if you want templates built this way: templateempire.io.

What would you need to see in a quality report before you trusted a template enough to build a business on it? Curious to hear, that answer shapes what I build next.

Auth in Next.js SaaS starters: redirect loops, OAuth callbacks, magic links, and session drift

Dan — Sat, 06 Jun 2026 20:38:26 +0000

A practical guide to auditing authentication in a Next.js SaaS starter before it breaks across preview URLs, production domains, and protected routes.

Authentication is one of the easiest features to demo and one of the easiest features to break.

A sign-in button proves almost nothing by itself. Real SaaS auth has to survive production domains, preview deployments, OAuth callbacks, magic links, session refresh, protected routes, billing states, role checks, account deletion, and sometimes organisations or custom domains.

When evaluating a Next.js SaaS starter, treat auth as a system, not a screen.

The happy-path demo hides the hard parts

The usual demo flow is simple:

Click sign in.
Use a test account.
Land on the dashboard.

That does not prove much.

Real users create edge cases immediately:

they click a magic link on another device;
they use Google OAuth on a preview deployment;
their session expires while a form is open;
they try to access /dashboard while logged out;
they cancel checkout and return later;
they use a workspace invite link;
they sign in with a different provider using the same email;
they delete their account;
they are removed from a team.

A production-ready starter should explain these paths or at least provide clean extension points.

Redirect loops usually mean route boundaries are unclear

Redirect loops happen when the application cannot clearly decide whether a route is public, auth-only, protected, or already authenticated.

Common causes include:

middleware running on routes it should ignore;
auth pages redirecting to dashboard while dashboard redirects back to auth;
callback routes being protected by mistake;
missing environment variables for the canonical app URL;
inconsistent trailing slash or base-path behaviour;
session checks that disagree between middleware and server components.

The fix is usually architectural rather than cosmetic. A good starter should have an explicit route map:

public marketing routes;
auth routes;
callback routes;
protected app routes;
admin routes;
API routes;
webhook routes.

If everything is protected by one broad matcher and exceptions are scattered around the codebase, expect pain.

OAuth callbacks need environment discipline

OAuth providers are strict about callback URLs. That is good security, but it creates setup friction.

A starter should document the callback URLs needed for:

local development;
preview deployments;
production;
custom domains;
subdomains if relevant.

It should also explain which environment variable represents the public application URL and how that value changes by environment.

Red flags:

callback URLs only shown for localhost;
no mention of preview URLs;
auth provider setup hidden behind “configure your provider”;
hard-coded base URLs;
no troubleshooting section for OAuth redirects.

If your buyer cannot configure OAuth without guessing, the starter is not handoff-ready.

Magic links need a clear product flow

Magic links are convenient, but they create state questions:

How long does the link last?
What happens if it is opened on another device?
Where does the user land after verification?
Does the app preserve the intended destination?
What happens if the user purchased before creating an account?
Are used or expired links handled clearly?

A starter that supports magic links should include the UX around them: email copy, expired-link screen, resend path, and redirect destination handling.

Auth is not only cryptography. It is also user experience.

Session drift creates confusing bugs

Session drift happens when different parts of the app disagree about who the user is or what they can access.

For example:

middleware sees a stale token;
a server component fetches a fresh user;
a client component still has old state;
billing status changed by webhook but the dashboard still shows old access;
a role changed but cached data still shows admin controls.

A robust SaaS starter defines where the source of truth lives.

For sensitive checks, prefer server-side decisions. Client state can improve interactivity, but it should not be the final authority for access.

Auth and billing should be connected carefully

Many SaaS starters treat auth and billing as separate modules. In the product, they interact constantly.

Questions to ask:

Can someone buy before creating an account?
If so, how is payment linked to the eventual user?
Can users sign up with OAuth after paying with an email link?
What happens if the billing email differs from the login email?
Can an unpaid user access account settings?
Can a cancelled user still log in but not use paid features?

A good starter does not need to force one answer. It should make the chosen answer explicit.

Roles should not be only visual

Hiding a button is not access control. If the server still accepts the action, the permission model is broken.

A SaaS starter should enforce permissions at the boundary where data changes or sensitive data is read.

Look for:

typed roles;
central permission helpers;
server-side checks;
protected admin routes;
audit logs for sensitive actions;
clear separation between billing entitlements and user roles.

Billing answers “has this account paid?” Roles answer “what can this user do?” They are related, but they are not the same.

Account lifecycle matters

Auth does not end at sign-in.

A production-ready starter should consider:

profile editing;
email changes;
password reset or provider-managed equivalent;
account deletion;
session invalidation;
data export;
team removal;
admin suspension;
audit logging.

Even if the template ships a lean version, the data model should not make these impossible later.

Auth audit checklist

Before trusting a Next.js SaaS starter’s auth layer, check:

[ ] Public, auth, callback, protected, admin, and webhook routes are separated.
[ ] Middleware or proxy matchers are documented.
[ ] The authoritative access check runs in a server component, route handler, or the data layer, not in middleware alone.
[ ] OAuth callback URLs are shown for local and production.
[ ] Preview URL behaviour is explained.
[ ] Magic link expiry and redirect behaviour is clear.
[ ] Sessions are checked server-side for sensitive routes.
[ ] Roles and permissions are typed or centralised.
[ ] Billing entitlements are not confused with user roles.
[ ] Account deletion and export are considered.
[ ] Auth errors have user-facing states.
[ ] The docs include common redirect and callback troubleshooting.

Template Empire angle

Template Empire treats auth as part of the foundation: route protection, user management, compliance scaffolding, billing interaction, and auditability all matter. The goal is not simply to make sign-in work in a demo. The goal is to make auth understandable enough that a buyer can safely build on it.