# fullstack-dev

> A Claude Code skill from MiniMax-AI's skills repo for full-stack architecture and frontend-backend integration — REST API design, auth flows (JWT + refresh, session, OAuth), real-time (SSE / WebSocket / polling), feature-first project layout, error handling hierarchies, and a mandatory five-step workflow that gates code-writing on architectural decisions.

**Use case**: Scaffold a full-stack app where the architectural decisions get made and stated before any feature code lands

**Canonical URL**: https://agentcookbooks.com/skills/fullstack-dev/

**Topics**: claude-code, skills, architecture

**Trigger phrases**: "scaffold a full-stack app", "Express + React with auth", "add SSE to my backend"

**Source**: [MiniMax-AI](https://github.com/MiniMax-AI/skills/tree/main/skills/fullstack-dev)

**License**: MIT

---

## What it does

`fullstack-dev` is the full-stack architecture skill in [MiniMax-AI's skills repo](https://github.com/MiniMax-AI/skills) — and the wedge is in step 0 of its mandatory workflow. Before scaffolding anything, the skill forces a six-question requirements gather: stack (language/framework for both ends), service type (API-only, full-stack monolith, microservice), database (SQL / NoSQL with specifics), integration (REST / GraphQL / tRPC / gRPC), real-time need (SSE / WebSocket / polling), and auth strategy (JWT / session / OAuth / third-party). If the user already specified those, the skill skips ahead — but if they didn't, it asks before any code.

Step 1 is architectural decisions stated up front: project structure (feature-first vs layer-first, with feature-first as the recommendation), API client approach (typed fetch vs React Query vs tRPC vs OpenAPI codegen), auth strategy (JWT + refresh vs session vs third-party), real-time method (polling vs SSE vs WebSocket), error handling (typed error hierarchy + global handler). One sentence per decision, made and stated before code lands. Step 2 runs the relevant scaffold checklist. Step 3 implements following the patterns referenced inline. Step 4 verifies — `npm run build` on both ends, smoke-test the endpoints with `curl`, integration check (CORS, API base URL, auth flow), real-time check (two browser tabs, verify changes sync). Step 5 produces a handoff summary: what was built, how to run it, what's missing, key files.

The reference catalog underneath: project structure & layering, error handling & resilience, API client patterns, authentication & middleware, file uploads, real-time patterns, configuration management, logging, caching, database access patterns, background jobs, testing pyramid, production hardening, contract tests. Sources cited explicitly: Twelve-Factor App, Clean Architecture, Domain-Driven Design, Patterns of Enterprise Application Architecture, Martin Fowler on testing pyramid and contract tests, the Google SRE Handbook on release engineering, and ThoughtWorks Technology Radar.

## When to use it

- Scaffolding a new full-stack application — backend + frontend together with integration patterns built in
- Picking a backend stack (Express + React, Django + Vue, Go + HTMX, Next.js full-stack) where the auth, real-time, and error-handling decisions need to be made up front
- Adding a real-time layer (SSE for one-way server pushes, WebSocket for bidirectional, polling for low-frequency / cache-friendly)
- Designing a typed error hierarchy with a global handler so the frontend can react to specific error classes
- Hardening an existing backend for production — config management, logging, caching, background jobs, contract tests

When *not* to reach for it:

- Pure frontend / UI / CSS work — the skill's `NOT for` list calls this out by name
- Pure database schema design without backend context — same exclusion
- Pure microservice infrastructure work where the per-service patterns matter more than the cross-service architecture
- A throwaway prototype where the step-0 requirements gather is overhead, not insurance

## Install

From [MiniMax-AI/skills](https://github.com/MiniMax-AI/skills) at `skills/fullstack-dev/`. Drop into `~/.claude/skills/fullstack-dev/`. Plugin marketplace install: `claude plugin marketplace add https://github.com/MiniMax-AI/skills` then `claude plugin install minimax-skills`.

The skill is pattern + checklist + reference text — it doesn't ship code generators. The toolchains (Node, Python, Go, databases) are installed locally.

## What a session looks like

1. **Step 0: requirements.** Skill asks the six questions. Operator answers (or has already answered in the prompt). Skill states the answers back as confirmation.
2. **Step 1: architectural decisions.** Skill states each decision and its one-sentence rationale — feature-first project structure, JWT + refresh token auth, SSE for real-time updates, typed `AppError` hierarchy with global Express middleware.
3. **Step 2: scaffold.** Skill runs the relevant checklist — backend service or full-stack app — and creates the project skeleton.
4. **Step 3: implement.** Routes, controllers, services, repositories, middleware, schemas, validators. The skill references specific section numbers from its own reference catalog as it implements (e.g. "applying Section 6 auth middleware here").
5. **Step 4: verify.** `npm run build` on backend and frontend. `curl /health` and `curl /api/<resource>`. CORS check. Auth flow check. Real-time check with two browser tabs.
6. **Step 5: handoff summary.** What was built, how to run it (exact commands), what's missing or deferred, key files to know about.

The discipline that makes it work: the step-0 requirements gather and the explicit architectural decisions in step 1. The skill refuses to start writing code until both are stated. That heads off the "we'll figure out auth later" / "we'll add real-time later" pattern that produces architectures that have to be unwound a quarter into the project.

## Receipts

_TODO — to be filled in from a real session. The fit is also wider than other entries on this wiki — full-stack scaffolding spans a lot of decisions, so receipts are easier to scope on a specific cut (e.g. "scaffolded a Node + React todo app with JWT-refresh auth and SSE updates"). Once the skill has been pointed at a real project, this section will capture: which architectural decisions the skill made and stated up front, whether the step-4 verification caught a real CORS or auth bug before the handoff, and whether the typed error hierarchy actually let the frontend react to specific error classes (most common failure mode: errors get caught generically on the frontend and the typing is lost in transit)._

## Source and attribution

From [MiniMax-AI's skills repository](https://github.com/MiniMax-AI/skills/tree/main/skills/fullstack-dev), an MIT-licensed skill collection. The skill cites Twelve-Factor App (12factor.net), Clean Architecture (Robert C. Martin), Domain-Driven Design (Eric Evans), Patterns of Enterprise Application Architecture (Martin Fowler), Martin Fowler on testing pyramid and contract tests, Google SRE Handbook, and ThoughtWorks Technology Radar as its sources.

License: MIT.

The wedge over a generic "full-stack dev" agent: the mandatory five-step workflow with explicit architectural-decision statement before code. Most full-stack scaffolding agents skip straight to code; this one gates code-writing on requirements + decisions + checklist, which is the discipline that separates architectures that hold up six months in from the ones that need an unwind.