Claude Code SaaS boilerplate: a NestJS template your agent can follow

CrabStack is a SaaS template written to be extended by Claude Code. The repo tells the agent where things go, gives it a skill for building a feature, and fails the build when it skips a step. This page shows what those files contain and how a session with Claude Code runs on it.

What Claude Code reads

• CLAUDE.md at the root is one line: @AGENTS.md. Claude Code loads AGENTS.md through it, so Claude Code, Cursor, Codex and Copilot read the same instructions.
• AGENTS.md describes the stack in a few lines, then has a "Find your task" table. Each row is a common task: add a module, add a field, add a page, gate a feature behind a subscription, send an email, add an MCP tool. For each one it names the doc to read first, the reference code to copy, and the check that fails if the agent gets it wrong.
• backend/CLAUDE.md and frontend/CLAUDE.md hold the conventions for each half: the module pattern, database rules, billing rules, and how pages call the API without exposing the session token.

The rules that matter most are also tests.

The new-module skill

.claude/skills/new-module/SKILL.md is a plain Markdown file. Claude Code loads it as a skill. Ask for "a projects module with CRUD" and it walks through every layer, copying the shape of the reference module:

1. A Knex migration, scoped to a workspace by default.
2. Zod schemas and DTOs.
3. The service and the controller.
4. Module registration and the route's access rule.
5. A regenerated openapi.json and frontend types.
6. A frontend page, if you want one.
7. Specs.
8. ./verify.sh. The module is not done until it passes.

Cursor, Codex and other tools can open the same file and follow it as written.

The checks that catch skipped steps

• Route access. Every route must appear in POLICY with its guards, or as public with a reason. A new route that is in neither fails route-auth.spec.ts. A second spec sends real requests and checks they are refused.
• Deletion rules. Every table needs an entry saying what account deletion does to it. A new table without one fails the build.
• API drift. A controller change without a regenerated openapi.json fails CI. So do frontend types that no longer match it.

One more check depends on the agent following the skill. The template ships an isolation spec for its items routes: a member of one workspace requests another workspace's items every way the routes allow and expects 404. Nothing enforces that spec for a new module. The skill's specs step tells the agent to add the new module's routes to it.

When Claude Code runs ./verify.sh, it gets a clear verdict. VERIFY_QUIET=1 streams the full output to .verify.log and prints only stage lines, test summaries and the result, which keeps the agent's context small.

Running the live app from Claude

The backend includes an admin MCP server at POST /admin/mcp/oauth with 17 tools. Connect Claude Desktop, Claude Code, Cursor, Codex or another MCP client to your deployed app, and the agent can publish blog posts, look up users and signup counts, read email queue stats, queue sends, and check a user's billing. Connecting is OAuth 2.1 with dynamic client registration and PKCE: you approve the client by signing in to the app as an admin, and every call checks you are still one. Each grant can be revoked from the backoffice.

A first session

Step 7 of the 8-step Getting Started guide builds a first feature with your agent: start Postgres with Docker Compose, describe the feature in one sentence, let the skill run to the end, read the diff, and commit when ./verify.sh is green.

Who it fits

• You build mostly with Claude Code and review more than you type.
• You want instructions the agent reads and tests that hold it to them.
• You want the agent to operate the deployed app as well as write it.

Who it does not fit

• You want the agent to work with no review at all. The checks catch skipped steps. They do not judge whether a feature is the right one.
• You cannot run Docker. Without it, the database tests skip and verify does not report green.
• You want Prisma, a frontend other than Next.js, or a payment provider other than Stripe.

Related

• NestJS SaaS boilerplate: everything that ships
• Vibe coding SaaS template: the same template for people who prompt more than they code
• NestJS and Next.js boilerplate: the two halves and their convention files
• NestJS multi-tenant boilerplate: what the isolation spec tests
• Docs: Build your first feature with your agent, Adding a Module, Admin MCP Server, Testing
• Compare: vs ShipFast, vs Makerkit, vs supastarter, and the ranking of boilerplates for AI agents

FAQ

Does CrabStack include a CLAUDE.md? Yes. The root CLAUDE.md loads AGENTS.md, and backend/CLAUDE.md and frontend/CLAUDE.md hold each half's conventions.

Does it work with Cursor or Codex as well? Yes. AGENTS.md is read by Cursor, Codex and Copilot. The new-module skill is plain Markdown that any agent can open and follow.

What stops Claude Code from shipping an unprotected route? route-auth.spec.ts fails for any route that does not state its guards or a reason for being public. A second spec sends real requests and checks the guarded ones are refused.

Can Claude manage my deployed app? Yes, through the admin MCP server. It has 17 tools for blog posts, users, email and billing lookups, and you connect it by signing in as an admin.

How many tests does the agent run? More than 1,000 test cases across the backend and frontend. ./verify.sh runs them with the lint, build and drift checks.