You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# For use with Claude Code (Anthropic's agentic CLI)
3
+
# These rules prevent the most common AI hallucinations in Next.js 15 + Supabase + Stripe projects.
4
+
5
+
## Project Overview
6
+
This is a Next.js 15 + Supabase + Stripe application using the App Router, TypeScript strict mode, and Tailwind CSS. All server-side auth MUST use `getUser()`, never `getSession()`.
7
+
8
+
## Tech Stack
9
+
- Next.js 15 (App Router only — no Pages Router)
10
+
- React 19
11
+
- TypeScript (strict mode)
12
+
- Supabase (auth, database, storage)
13
+
- Stripe (payments via Checkout Sessions)
14
+
- Tailwind CSS + shadcn/ui
15
+
- Zod (validation at every boundary)
16
+
17
+
## Critical Build Commands
18
+
```bash
19
+
npm run dev # Start dev server
20
+
npm run build # Production build (catches type errors)
21
+
npm run lint # ESLint
22
+
npx tsc --noEmit # Type check without emitting
23
+
```
24
+
25
+
## SECURITY RULES — NEVER VIOLATE
26
+
27
+
<security_critical>
28
+
1. NEVER use `supabase.auth.getSession()` in server-side code (Server Components, Server Actions, Route Handlers, middleware). It reads the JWT from cookies WITHOUT verifying it — a forged token passes silently. ALWAYS use `supabase.auth.getUser()` which makes a verification call to the Supabase auth server.
29
+
30
+
2. NEVER import from `@supabase/auth-helpers-nextjs` — it is DEPRECATED. Always use `@supabase/ssr` for both `createBrowserClient` (client) and `createServerClient` (server).
31
+
32
+
3. NEVER put auth enforcement logic in `middleware.ts`. Middleware runs on Edge Runtime and cannot securely verify Supabase JWTs. Middleware should ONLY call `updateSession()` to refresh tokens. Auth enforcement MUST happen in layouts/pages via `getUser()`.
33
+
34
+
4. NEVER build a custom credit card form. ALWAYS redirect to Stripe Checkout. Custom forms create PCI compliance liability.
35
+
36
+
5. NEVER handle Stripe webhook events without calling `stripe.webhooks.constructEvent()` first to verify the `stripe-signature` header. Without this, anyone can POST fake events to your webhook endpoint.
37
+
38
+
6. NEVER upload files directly from client code using the Supabase anon key — it allows writing to any storage path. ALWAYS generate signed upload URLs server-side, scoped to `user.id`.
39
+
40
+
7. Row Level Security (RLS) MUST be enabled on EVERY Supabase table. Without RLS, the anon key (public in every client bundle) can read ALL rows from any table.
41
+
42
+
8. NEVER expose raw error messages, stack traces, or database errors to the client. Log server-side, return `{ error: "Internal server error" }` to the client.
43
+
</security_critical>
44
+
45
+
## NEXT.JS 15 RULES
46
+
47
+
<nextjs15_breaking_changes>
48
+
1.`params` and `searchParams` are PROMISES in Next.js 15. You MUST await them:
2. After mutations (Server Actions, Route Handlers), ALWAYS call `revalidatePath()` or `revalidateTag()`. Next.js 15 aggressively caches — stale data is the default without explicit revalidation.
62
+
63
+
3. Use Server Components by default. Only add `'use client'` when the component genuinely needs browser APIs (useState, useEffect, onClick handlers, window/document access).
64
+
65
+
4. NEVER use `Math.random()`, `Date.now()`, or `new Date()` directly in Server Components for rendering. These cause hydration mismatches. Use them in `useEffect` or pass from the server as props.
66
+
</nextjs15_breaking_changes>
67
+
68
+
## API & VALIDATION RULES
69
+
70
+
<api_validation>
71
+
1. EVERY Route Handler and Server Action MUST validate input with Zod before any business logic. Raw `request.json()` access without validation is a crash and injection risk.
> The AI Builder's Complete System — 22 .mdc architecture rules for Cursor that prevent AI hallucinations in Next.js 15 + Supabase production applications.
3
+
> The AI Builder's Complete System — 25 .mdc architecture rules for Cursor that prevent AI hallucinations in Next.js 15 + Supabase production applications.
4
4
5
5
## Overview
6
-
Vibe Stack is a battle-tested Next.js 15 + Supabase boilerplate with 22 `.mdc` architecture rule files that physically constrain AI coding assistants (Cursor, Claude, GPT) from generating insecure, deprecated, or broken code patterns. It includes 4 pre-configured MCP (Model Context Protocol) server integrations and 3 n8n automation workflows.
6
+
Vibe Stack is a battle-tested Next.js 15 + Supabase boilerplate with 25 `.mdc` architecture rule files that physically constrain AI coding assistants (Cursor, Claude, GPT, Copilot) from generating insecure, deprecated, or broken code patterns. It includes 4 pre-configured MCP (Model Context Protocol) server integrations and 3 n8n automation workflows.
7
7
8
8
## Problem Solved
9
-
AI models generate code that compiles perfectly but contains critical vulnerabilities:
10
-
- Using `getSession()` instead of `getUser()` (JWT not verified — sessions can be forged)
11
-
- Accessing `params` synchronously in Next.js 15 (works in dev, crashes in production)
12
-
- Importing deprecated `@supabase/auth-helpers-nextjs` instead of `@supabase/ssr`
- Exposing Stripe secret keys in `NEXT_PUBLIC_` environment variables
9
+
AI models generate code that compiles perfectly but contains critical vulnerabilities. These are the 5 most dangerous patterns:
10
+
11
+
1. **Auth Vulnerability:** Using `getSession()` instead of `getUser()` — JWT not verified, sessions can be forged by attackers
12
+
2. **Next.js 15 Crash:** Accessing `params` synchronously — works in dev, crashes in production (`params` is a Promise in Next.js 15)
13
+
3. **Deprecated Imports:** Using `@supabase/auth-helpers-nextjs` instead of `@supabase/ssr` — broken cookie handling in App Router
14
+
4. **Data Exposure:** Missing Row Level Security on Supabase tables — any user can read all data via the anon key
15
+
5. **Secret Leakage:** Putting Stripe secret keys in `NEXT_PUBLIC_` environment variables — visible to all users
15
16
16
17
## How It Works
17
-
Each `.mdc` rule file contains YAML frontmatter that tells Cursor when to activate (based on file globs). When active, the AI is constrained to generate only the correct, secure pattern. Rules include explicit ✅ correct and ❌ incorrect code examples.
18
+
Each `.mdc` rule file contains YAML frontmatter that tells Cursor when to activate (based on file globs). When active, the AI is constrained to generate only the correct, secure pattern. Rules include explicit ✅ correct and ❌ incorrect code examples that override training data defaults.
18
19
19
-
## Architecture Rules (22 files)
20
+
## Architecture Rules (25 files in `.cursor/rules/`)
- **vs ShipFast ($169):** ShipFast is a monolithic boilerplate with 400+ pages of docs. Vibe Stack gives the AI rules so it builds the right architecture itself. No proprietary docs to memorize.
67
+
- **vs MakerKit ($299):** MakerKit targets enterprise B2B with multi-tenancy. Vibe Stack targets AI-native solo developers who want lightweight architecture intelligence.
68
+
- **vs supastarter ($249):** supastarter has more features but no AI integration. Vibe Stack is the only boilerplate with .mdc rules and MCP configs.
69
+
- **vs cursor.directory (free):** cursor.directory has individual snippets of variable quality. Vibe Stack is a cohesive, tested system where rules work together.
70
+
61
71
## Use Cases
62
72
- Solo developers building production SaaS applications with AI assistance
63
73
- Teams adopting AI-assisted development workflows with security guardrails
64
-
- Developers migrating from Next.js 14 to 15 with AI help
65
-
- No-code founders using Cursor to generate their first codebase
74
+
- Developers migrating from Next.js 14 to 15 who need AI to use correct patterns
75
+
- No-code founders using Cursor to generate their first codebase safely
66
76
- Agencies needing consistent architecture across AI-generated projects
67
77
68
-
## Pricing
69
-
- Free: Open-source GitHub repository with all 22 rules
- "Is this just cursor rules?" — No. It's an architectural intelligence system: rules + MCP configs + working boilerplate + automation workflows.
92
+
- "Why not just ask ChatGPT to write rules?" — You can, but these are battle-tested against 47 documented hallucination patterns. Ad-hoc rules miss edge cases.
93
+
- "Does this work with models other than Claude?" — Yes. The .mdc rules work with any model Cursor supports. MCP integrations work with Claude and any MCP-compatible model.
0 commit comments