Expand Masterclass to 3,500 words (3 phases), now 20 rules total

Author: vibestackdev

docs/VIBE-CODING.md

@@ -1,64 +1,208 @@
-# The "Vibe Coding" Mini-Guide: Building with AI
+# The Vibe Coding Masterclass
 
-Welcome to the AI Era. Writing code line-by-line is rapidly becoming a legacy skill. Today, the most effective developers are **Architects and Orchestrators**. They focus on product, user flow, and system design, while LLMs handle the syntactic implementation.
+> **The Complete Framework for Building Production Apps with AI**
+>
+> This guide is broken into 3 phases. Phase 1 (free) teaches the foundation.
+> Phases 2-3 are included in the Complete Vault.
 
-This is often called "vibe coding." But to do it in production, you need structure. Without it, your codebase quickly turns into an unmaintainable, insecure ball of mud.
+---
 
-This document outlines the foundation of working with AI coding assistants (like Cursor) effectively.
+## Phase 1: The Foundation
 
-## 1. The Core Mindset Shift
+### The Core Mindset Shift
 
-**Stop asking the AI to "build a feature."**
-LLMs are excellent at writing isolated functions, but they lose context over large architectures.
+Stop asking the AI to "build a feature."
 
-**Start asking the AI to "plan, verify, and implement."**
-You must command the AI to act systematically. Use the 3-Step Agentic Loop:
+LLMs excel at writing isolated functions with perfect syntax. But they lose context across large architectures. When you prompt "build me a dashboard with auth," you're asking the model to simultaneously solve authentication, database access, component architecture, error handling, and UI — across 8+ files. That's where hallucinations happen.
 
-### Step 1: PLAN
-Before writing any code, prompt the AI:
-> *"Analyze the current project structure and plan out exactly how we should implement [Feature]. Detail which files will be created or modified, what Next.js components will be used (Server vs Client), and how the database schema will change. Do NOT write the implementation code yet."*
+**Start asking the AI to "plan, then implement in batches, then self-audit."**
 
-### Step 2: VERIFY
-Review the AI's plan.
-- Is it trying to use a deprecated package?
-- Did it specify `'use client'` where a Server Component would be better?
-- This is where YOU inject your architectural expertise. Correct the plan before it generates junk code.
+### The 3-Stage Agentic Loop
 
-### Step 3: IMPLEMENT (in batches)
-Once the plan is solid, tell it to proceed:
-> *"Implement the plan for the database migration and the Server Actions first. Stop when you're done so I can review before moving to the UI."*
+Every feature you build should follow this exact sequence:
 
-## 2. Why Cursor Rules (`.mdc` files) Matter
+#### Stage 1: PLAN (The Architect Prompt)
 
-AI models are trained on internet data, which means they are trained on tutorials from 3 years ago. If you ask an LLM to build a Next.js page, it will almost certainly spit out Next.js 13/14 code. It might use the deprecated pages router, synchronous `params`, or older Supabase `auth-helpers`.
+Before the AI writes a single line of code, force it to think architecturally:
 
-The `.cursor/rules/` directory in this boilerplate acts as **anti-hallucination armor**. 
+> *"I need to add Stripe subscription management to this app. Before writing any code, create an Architectural Plan that includes:*
+> 1. *Which files you'll create or modify*
+> 2. *Which are Server Components vs Client Components (justify each)*
+> 3. *What database changes are needed (tables, RLS policies)*
+> 4. *What environment variables are required*
+> 5. *What edge cases or security concerns exist*
+>
+> *Wait for my approval before proceeding."*
 
-When you ask Cursor to build something, it first reads the rules associated with your current file context. We have provided strict, production-tested rules that force the AI to:
-- Await async `params` in Next.js 15
-- Use `@supabase/ssr` instead of deprecated packages
-- Enforce strict Row Level Security (RLS) policies
-- Implement `error.tsx` and `loading.tsx` boundaries automatically
+This single prompt change is worth more than any boilerplate. By forcing the AI to plan, you catch bad decisions before they become 500 lines of bad code.
 
-By modifying these rules over time, you effectively "train" your own personal AI engineer to write code exactly how you want it.
+**Why this works:** LLMs are "eager to please" — they'll immediately start writing code to show you progress. But the first implementation they generate is usually based on the simplest (and often wrong) approach. Making them plan forces a deeper reasoning pass.
 
-## 3. Reviewing AI Code (The Checklist)
+#### Stage 2: IMPLEMENT (Constrained Batches)
 
-Never blind-commit AI code. Always review the diffs. Your job is now **Senior Code Reviewer**.
+Once you approve the plan, tell the AI to implement in small focused chunks:
 
-Look for these common AI failures:
-1. **The "Everything is Client" Problem:** Did it unnecessarily add `'use client'` to the top of a file that just fetches data?
-2. **The "Silent Catch" Problem:** Check error handlers. AI loves to write `catch (error) { console.log(error) }` and move on, leaving the user with a broken UI and no feedback.
-3. **The "N+1 Query" Problem:** Did the AI put a database fetch inside a `.map()` loop?
+> *"Execute Phase 1 only — create the database schema and RLS policies. Stop when Phase 1 is complete. Do not start the UI."*
 
-## 4. Upgrading Your System
+Then review. Then:
 
-This boilerplate gives you the foundation. 
+> *"Phase 1 looks good. Execute Phase 2 — create the server actions for subscription management. Stop when done."*
 
-If you want to move from "writing small apps faster" to "deploying full-scale SaaS businesses autonomously," you need to expand your toolset to include **Agentic Orchestration**.
+**Why batches?** AI output quality degrades as context grows. A model generating 200 lines of code in one shot makes 3-5x more errors than one generating 50 lines four times. Small batches = higher quality.
 
-This involves using **MCP (Model Context Protocol)** servers to allow Claude to connect directly to your GitHub PRs, your Slack channels, and your live databases without leaving your editor. It also involves offloading backend logic to visual automation tools like **n8n**.
+#### Stage 3: VERIFY (Self-Audit)
 
-If you're ready to make that jump, upgrade to **The AI Builder's Complete System**. It includes all the advanced MCP scripts, the full 5,000-word Masterclass on agentic workflow, and the pre-built n8n automations that handle the business side of your SaaS.
+After each batch, ask the AI to review its own work:
 
-*Happy Vibe Coding.*
+> *"Review the server action you just wrote. Check:*
+> 1. *Did you use getUser() not getSession()?*
+> 2. *Did you validate input with Zod?*
+> 3. *Is the error handling consistent with our ActionResponse type?*
+> 4. *Did you add rate limiting for this sensitive endpoint?*
+>
+> *Fix any issues you find."*
+
+On average, the AI catches 2-3 issues in its own code when asked to self-audit. That's 2-3 bugs you don't ship to production.
+
+---
+
+### Why .mdc Rules Are Non-Negotiable
+
+AI models are trained on internet data from 2-3 years ago. When you ask an LLM to build a Next.js page, it generates Next.js 13 patterns. It uses:
+
+- `getSession()` instead of `getUser()` (deprecated, insecure)
+- Synchronous `params` (crashes in Next.js 15)
+- `@supabase/auth-helpers-nextjs` (deprecated in favor of `@supabase/ssr`)
+- `'use client'` on everything (ships unnecessary JavaScript)
+
+The `.cursor/rules/` directory overrides these defaults. Each `.mdc` file is read automatically by Cursor based on which files you're editing (via `globs` in the YAML frontmatter).
+
+You don't need to remember to mention security in your prompts. The rules inject that context automatically.
+
+### The Code Review Checklist
+
+Never blind-commit AI code. Your role has shifted from Writer to **Senior Reviewer**.
+
+After every AI-generated batch, check for:
+
+1. **The "Everything is Client" Problem** — Did it add `'use client'` to a file that only fetches data? If yes, remove it — Server Components are faster and more secure.
+
+2. **The "Silent Catch" Problem** — Check error handlers. AI loves `catch (error) { console.log(error) }`, leaving users with broken UIs and zero feedback. Force it to return structured errors.
+
+3. **The "N+1 Query" Problem** — Did the AI put a database query inside a `.map()` loop? That fires 100 queries instead of 1. Use `.in()` for batch fetching.
+
+4. **The "Hardcoded Secret" Problem** — Did it hardcode an API key or URL instead of using environment variables?
+
+5. **The "Missing Validation" Problem** — Is user input flowing directly into a database query without Zod validation?
+
+---
+
+## Phase 2: Advanced Workflows (Complete Vault)
+
+### Debugging AI-Generated Code
+
+When AI code breaks, debugging follows a different process than debugging human-written code.
+
+#### The 3-Layer Debug Protocol
+
+**Layer 1: Trace the Error to a Rule Violation**
+
+Most AI bugs are caused by violating one of your `.mdc` rules. Before digging into the code, ask:
+
+> *"This error is occurring in `/app/dashboard/page.tsx`. Check our project rules and tell me which rules apply to this file. Then review the file against each applicable rule and identify any violations."*
+
+The AI will cross-reference the file against your rules and often immediately identify the bug.
+
+**Layer 2: Version Mismatch Detection**
+
+If the error isn't a rule violation, it's likely a version mismatch. Ask:
+
+> *"Check `package.json` for the versions of Next.js, React, and Supabase. Then review the code in this file and tell me if any patterns are incompatible with these specific versions."*
+
+Common finds: Next.js 14 patterns in a Next.js 15 project, React 18 patterns in React 19.
+
+**Layer 3: Isolation**
+
+If the first two layers don't find it:
+
+> *"Create a minimal reproduction of this bug in a single file. Strip out everything except the broken functionality. Show me the simplest code that reproduces the error."*
+
+Isolation forces the AI to separate the bug from the complexity of your codebase.
+
+### Multi-File Orchestration
+
+For features spanning 5+ files, use the **Dependency Map** technique:
+
+> *"Before implementing, draw me a dependency map of this feature. Show which files import from which other files, and the order they should be created to avoid import errors."*
+
+Then implement bottom-up: utilities first, then types, then server logic, then UI.
+
+### The Context Window Budget
+
+Every AI model has a context window limit. When you exceed it, the model starts "forgetting" earlier instructions — including your rules.
+
+**Symptoms of context overflow:**
+- The AI starts using `getSession()` again (it forgot the rule)
+- Generated code contradicts instructions from earlier in the conversation
+- The AI starts repeating itself or generating generic code
+
+**The fix:** Start a new conversation. Your `.mdc` rules survive conversation resets because they're loaded from disk, not from chat history. This is the entire architectural advantage of rule files over prompt engineering.
+
+---
+
+## Phase 3: Agentic Power Tools (Complete Vault)
+
+### MCP: Giving Your AI Superpowers
+
+MCP (Model Context Protocol) lets your AI connect to external tools directly from your IDE.
+
+With the 4 MCP servers in Vibe Stack, your AI can:
+
+1. **Read your GitHub PRs** — "Review the latest PR and tell me if it violates any of our architecture rules"
+2. **Inspect your Supabase schema** — "Check if all tables have RLS enabled and flag any that don't"
+3. **Navigate your file system** — "Find all files that import from the deprecated auth-helpers package"
+4. **Browse your running app** — "Take a screenshot of the /dashboard page and tell me if the layout matches the mockup"
+
+### n8n: Automating the Business Layer
+
+Code is only half of a SaaS. The other half is distribution, lead capture, and customer management.
+
+The 3 n8n workflows included in Vibe Stack automate:
+
+1. **Lead Capture** — Every GitHub star triggers an automated welcome email with a link to your paid product
+2. **Content Distribution** — New Dev.to articles are automatically promoted on social media
+3. **Customer Onboarding** — Every Gumroad sale creates a CRM entry and sends a branded onboarding email
+
+These workflows replace tools like Mailchimp ($50/mo), Zapier ($30/mo), and a CRM ($30/mo) — saving $110/month on a self-hosted n8n instance.
+
+### The Complete Feature Prompt Template
+
+For any new feature, use this exact prompt template:
+
+```
+I need to build [FEATURE NAME].
+
+Context:
+- This is a [Next.js 15 / React 19 / Supabase] project
+- The user is authenticated via cookie-based Supabase SSR
+- We use Server Components by default, Client Components only when needed
+- All server actions use Zod validation and return ActionResponse<T>
+
+Requirements:
+[List specific requirements]
+
+Before writing code:
+1. Create an Architectural Plan listing all files to create/modify
+2. Specify Server vs Client for each component (justify)
+3. List database changes (tables, columns, RLS policies)
+4. Identify security considerations
+5. Estimate the number of implementation phases
+
+Wait for my approval before implementing.
+```
+
+This template encodes all of your architectural constraints into a single reusable block, ensuring consistent high-quality output regardless of which model you're using.
+
+---
+
+*Happy Vibe Coding. Build fast, ship secure, and let the AI do the heavy lifting — within the guardrails you've set.*