Next.js 15 — Production Architecture & Agent Playbook

27 architecture rules preventing AI hallucinations: insecure auth (getSession vs getUser), synchronous params, deprecated imports, missing RLS, and Stripe

---
name: next-js-15-supabase-typescript-security
description: 27 architecture rules preventing AI hallucinations: insecure auth (getSession vs getUser), synchronous params, deprecated imports, missing RLS, and Stripe key exposure. Built for Cursor Agent and Claude Code. Use when working with Next.js 15, Supabase, TypeScript.
triggers:
  - next js 15 supabase typescript security
  - next.js 15
  - supabase
---

# Next.js 15 — Production Architecture & Agent Playbook

## 1. When to Use This Skill
Load `skill-next-js-15-supabase-typescript-security` whenever an engineering, architecture, or operations task involves **Next.js 15, Supabase, TypeScript**. Specifically:
- 27 architecture rules preventing AI hallucinations: insecure auth (getSession vs getUser), synchronous params, deprecated imports, missing RLS, and Stripe key exposure. Built for Cursor Agent and Claude Code.
- Designing, reviewing, refactoring, or debugging production configurations without guesswork or deprecated flags.
- Running deterministic pre-flight validation and post-execution verification checks before reporting completion.

## 2. Prerequisites & Required Environment
- **Target Stack:** Next.js 15, Supabase, TypeScript
- **Permissions Boundary:** Read-only inspection by default; ask for explicit human confirmation before executing destructive mutations or production deployments.
- **Reference Specification:** `https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/nextjs15-supabase-cursorrules-prompt-file.mdc`

## 3. Step-by-Step Execution Playbook
1. **Context & Configuration Discovery:**
   Inspect existing project manifests (`package.json`, `tsconfig.json`, `pyproject.toml`, `Cargo.toml`, `wrangler.jsonc`, or schema declarations) before proposing changes. Never overwrite existing bindings or credentials blindly.
2. **Deterministic Implementation:**
   Apply the canonical production patterns for **Next.js 15**:
   - Enforce strict schema and type validation at every external boundary.
   - Include explicit error handling, structured telemetry, and idempotency keys on all mutating calls.
   - Keep secrets in environment variables or managed secret stores—never hardcode tokens in source files.
3. **Verification & Regression Gate:**
   Run the verification commands below and inspect both exit codes and output payloads before marking the task complete.

## 4. Reference Commands & CLI Workflow
```bash
npx lightstate install skill-next-js-15-supabase-typescript-security
git status --short
npm test || pytest || cargo test
```

## 5. Edge Cases & Anti-Hallucination Guardrails
- **Zero Unverified Claims:** Never claim a build, migration, test run, or API call succeeded without inspecting the command output or HTTP status code.
- **Rollback Readiness:** Always record the previous state or migration version so changes can be reverted cleanly if downstream health checks fail.

Synthesized Engineering Blueprint & Setup Guide