The Vibe Coding Bible

The Zero to One Guide

Welcome! If you think "Terminal" is a disease or "Python" is a snake, this is for you.

You are not early to a trend. You are early to mastering it.

How to Use This Guide

Difficulty Levels

Learning Paths

🚀 Path A: Complete Beginner
Start at Chapter 1, work through in order, do every exercise.

⚡ Path B: Know Some React
Skim Chapters 1-2, focus on State Management and Performance.

🎯 Path C: Quick Reference
Jump to appendices, use Glossary for unfamiliar terms.

1. The Vibe Coding Mindset

🟢 Beginner | Prerequisites: None

Vibe coding is building software by collaborating with AI—describing what you want, reviewing what it produces, and guiding it toward better solutions.

TIP: The best vibe coders aren't the best typists—they're the best communicators.

Visualizing the Architect (You) vs Builder (AI) relationship

You Are the Architect, AI Is the Builder

The Three Laws of Vibe Coding

Law 1: Garbage In, Garbage Out
Vague prompts produce vague code. Be specific.

❌ VAGUE
"Make a button"

✅ SPECIFIC
"Make an accessible button with loading state and size variants (sm, md, lg)"

Law 2: Trust but Verify
AI confidently produces broken code. It PREDICTS, doesn't KNOW. Always test.

Law 3: Iterate, Don't Regenerate
When code isn't right, tell AI specifically what's wrong. Don't start over.

1a. The ARC Method

Architect. Refine. Check.

The most effective way to build software with AI is to use the right kind of thinking for the right stage of development—not one session doing everything at once. I call this the ARC Method: Architect, Refine, Check. It's a sequence of three roles, not a shopping list of specific products. Fill each role with whatever model or tool you have—the method still works when the brand names change.

Two ways to run it

ARC doesn't require three separate products—it requires three separate passes with three different mindsets. Pick the shape that fits your stack:

Whichever shape you pick, the Check phase only earns its keep if it comes from a genuinely different vantage point—a fresh session at minimum, a different model tier ideally, a different vendor when the stakes are high. See Chapter 22 (Multi-Agent Review) for a deeper review stack, and your context files for keeping every phase honest about the same project rules.

1b. Context Files

🟢 Beginner | Prerequisites: Chapter 1a

Give your AI a long-term memory.

Every new AI session starts with zero memory of your project. Context files fix that: markdown files in your repo that tools load automatically so the model gets your stack, standards, and goals every time.

The three files to know

CLAUDE.md starter template

Drop this in the project root and customize. Specific beats vague.

# Project Context

## Stack
- Framework: Next.js (App Router)
- Language: TypeScript (strict)
- Styling: Tailwind CSS
- State: [Zustand / TanStack Query / etc.]
- Database: [your DB]
- Auth: [your provider]

## Code standards
- Components: functional only
- File naming: kebab-case files, PascalCase components
- Always handle loading and error states
- No `any` — use `unknown` and narrow
- Prefer named exports

## What NOT to do
- No `useEffect` for server data — use a data library
- Do not install packages without asking
- No comments that only restate the code
- No inline styles unless agreed

## Architecture
- UI primitives → `/components/ui/`
- Features → `/components/features/` (or `/features/`)
- API clients → `/lib/api/`
- Shared types → `/types/`

## Tone
- Code should read like documentation
- Prefer explicit over clever

AGENTS.md starter (permissions)

# Agent Instructions

## Permissions
- You MAY read and edit files in `/src/`
- You MAY run `npm test` and `npm run build`
- You MAY NOT modify `/public/` without confirming first
- You MAY NOT commit directly to `main`

## Workflow
1. Before generating code: re-read the relevant files in context
2. After generating code: run lint and type-check
3. If uncertain: ask before acting, not after

## Off-limits
- Never touch auth-related files without explicit instruction
- Never modify `.env` files
- Never delete files — move to `/archive/` instead

The Contract File System

How to keep Claude Code and Cursor in sync across backend and frontend.

The hardest problem in a multi-tool AI workflow isn't getting one tool to build something well—it's keeping two tools aligned on the same system. Claude Code builds your backend. Cursor builds your frontend. Without a shared source of truth, they drift. An API endpoint gets renamed. A type changes shape. A field gets added. One tool knows. The other doesn't. That's how bugs get born.

Contract files solve this. They're .md files that define the exact interface between backend and frontend—written once, committed to the repo, and referenced by both tools before they touch anything that crosses that boundary.

The three contract files

The workflow

The API_CONTRACT.md template

# API Contract
Last updated: [date]
Backend: Claude Code | Frontend: Cursor

---

## Authentication

### POST /api/auth/login
**Request:**
```json
{
  "email": "string",
  "password": "string"
}
```
**Response (200):**
```json
{
  "user": {
    "id": "string (uuid)",
    "email": "string",
    "name": "string",
    "role": "admin | member"
  }
}
```
**Errors:**
- 401: Invalid credentials → `{ "error": "INVALID_CREDENTIALS" }`
- 429: Rate limited → `{ "error": "RATE_LIMITED", "retryAfter": number }`

**Auth:** None required
**Notes:** Session set via httpOnly cookie on success. No token in response body.

---

## Users

### GET /api/users/:id
**Request:** None
**Response (200):**
```json
{
  "id": "string",
  "email": "string",
  "name": "string",
  "createdAt": "ISO 8601 string"
}
```
**Errors:**
- 404: User not found → `{ "error": "USER_NOT_FOUND" }`

**Auth:** Required (session cookie)
**Notes:** Returns only public-safe fields. Never returns passwordHash.

The TYPES_CONTRACT.md template

# Types Contract
Last updated: [date]
Source of truth for all shared types between backend and frontend.
Both Claude Code and Cursor must reference this before creating or
modifying any type used across the stack boundary.

---

## Core Domain Types

```typescript
// User — used in auth, profile, and permission checks
interface User {
  id: string         // UUID
  email: string
  name: string
  role: 'admin' | 'member'
  createdAt: string  // ISO 8601
}

// API response wrapper — all endpoints return this shape
interface ApiResponse<T> {
  data: T | null
  error: string | null  // error code string, not user-facing message
}

// Pagination — used on all list endpoints
interface PaginatedResponse<T> {
  items: T[]
  total: number
  page: number
  pageSize: number
  hasMore: boolean
}
```

---

## Change Log
| Date | Change | Who |
|------|--------|-----|
| 2026-04-10 | Added `role` field to User | Claude Code |
| 2026-04-08 | Added PaginatedResponse | Claude Code |
| 2026-04-07 | Initial types | Claude Code |

Where these files live

project-root/
├── CLAUDE.md              ← Project rules + stack (Claude Code reads this)
├── AGENTS.md              ← Agent workflow rules
├── API_CONTRACT.md        ← Endpoint specs (Claude Code writes, Cursor reads)
├── TYPES_CONTRACT.md      ← Shared types (both tools read and write)
├── STATE_CONTRACT.md      ← Store shape (Claude Code writes, Cursor reads)
├── PROMPTS.md             ← Architecture decisions log
└── src/
    ├── app/               ← Frontend (Cursor)
    └── api/               ← Backend (Claude Code)

All contract files live at the project root—same level as your context files. They're committed to the repo and version-controlled. When a contract changes, the git diff tells you exactly what shifted between backend and frontend. That's your audit trail.

2. Prompt Engineering

🟢 Beginner | Prerequisites: Chapters 1–1b

The quality of AI-generated code depends entirely on how you ask.

The 5 Parts of a Great Prompt

The self-review prompt

After the model generates code, ask it to review its own work. Critique mode catches issues generation mode skipped—the task changed from “produce” to “audit.”

❌ STOP HERE (common mistake)
"Build me email + password authentication."
[AI generates code]
[You ship]

✅ ADD THIS AFTER
"Now review the code you just generated. Check for:
- Security issues (especially password/session handling)
- Edge cases that are not handled
- Types that could be tighter
- Anything that would fail in production
What would you change?"

The creative latitude unlock

Add this to the end of meaty feature prompts to shift from “execute the spec” to “senior collaborator”—you will get accessibility, loading states, and guardrails you forgot to list.

Add to the end of your prompt:

"You're free to add any functionality you think will be necessary or
valuable for this feature. Use your judgment."

🥋 The Prompt Dojo (Try it yourself)

See the difference between a lazy prompt and a Vibe prompt.

3. Philosophy

🟢 Beginner | Prerequisites: Chapters 1-2

These principles guide every coding decision. Internalize them to spot problems instantly.

The 7 Principles

1. Clarity > Cleverness: Readable beats impressive
2. Explicit > Implicit: Obvious beats magical
3. Composition > Inheritance: Small pieces beat hierarchies
4. Colocation: Related code stays together
5. Deletion > Abstraction: Simple beats flexible
6. Performance by Default: Fast is a feature
7. Accessibility Always: Build for everyone

1. CLARITY over cleverness

// ❌ CLEVER BUT CONFUSING
const r = a?.b?.c ?? d?.e ?? "default"

// ✅ CLEAR AND READABLE
const userCity = user?.address?.city
const defaultCity = settings?.defaultCity
const city = userCity ?? defaultCity ?? "Unknown"

4. Architecture

🟢 Beginner | Prerequisites: Chapter 3

Structure of a scalable Next.js 16 Application

Next.js App Structure

src/
├── app/                    # Routes (pages)
│   ├── page.tsx            # Home page (/)
│   ├── about/
│   │   └── page.tsx        # About page (/about)
│   ├── dashboard/
│   │   ├── page.tsx        # Dashboard page
│   │   └── layout.tsx      # Dashboard layout
│   └── layout.tsx          # Root layout
├── components/
│   ├── ui/                 # Primitives (Button, Input, Card)
│   └── features/           # Feature components (UserCard, ProductList)
├── hooks/                  # Custom React hooks
├── lib/                    # Utilities and helpers
│   ├── api/                # API client functions
│   └── utils/              # Helper functions
└── types/                  # TypeScript type definitions

5. TypeScript

🟡 Intermediate | Prerequisites: Basic JavaScript, Chapter 4

TypeScript catches bugs before runtime. Enables autocomplete. Serves as documentation.

Discriminated Unions

type AsyncState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error }

function handleState(state: AsyncState<User>) {
  if (state.status === "success") {
    console.log(state.data.name)  // ✅ TypeScript knows data exists!
  }
}

6. Naming Conventions

🟢 Beginner | Prerequisites: Chapters 3-4

7. React Components

🟡 Intermediate | Prerequisites: Basic React, Chapter 5

Component Structure Order

1️⃣ TYPES          interface Props { ... }
2️⃣ COMPONENT      export function Name({ props }) {
3️⃣ HOOKS          const [state] = useState()
4️⃣ DERIVED        const fullName = first + last
5️⃣ HANDLERS       const handleClick = () => { }
6️⃣ EARLY RETURNS  if (loading) return <Skeleton />
7️⃣ RETURN         return ( <div>...</div> )

8. State Management

🟡 Intermediate | Prerequisites: Chapter 7

State Hierarchy

9. Styling

🟢 Beginner | Prerequisites: Basic CSS, Chapter 7

We use Tailwind CSS for utility-first styling.

Class Order Convention

Layout → Sizing → Spacing → Typography → Colors → Borders → Effects → States

// ✅ ORGANIZED - follows order
className="flex p-4 text-white font-medium bg-blue-600 rounded-lg hover:bg-blue-700"

10. Performance

🟡 Intermediate | Prerequisites: Chapter 8

1-second delay = 7% fewer conversions.

Code Splitting

import { lazy, Suspense } from "react"

const Dashboard = lazy(() => import("./pages/Dashboard"))

function App() {
  return (
    <Suspense fallback={<LoadingSkeleton />}>
      <Dashboard />
    </Suspense>
  )
}

11. Accessibility

🟡 Intermediate | Prerequisites: Chapter 7

The #1 Rule: Use Semantic HTML

// ❌ NEVER - not accessible
<div onClick={handleClick}>Click me</div>

// ✅ ALWAYS - accessible by default
<button onClick={handleClick} type="button">Click me</button>

12. Error Handling

🟡 Intermediate | Prerequisites: Chapters 5, 8

Every async operation has THREE states. Handle ALL of them: Loading, Error, Success.

13. Security

🔴 Advanced | Prerequisites: Chapters 5, 8, 12

The #1 Rule: Never Store Tokens in localStorage

// ❌ NEVER - JavaScript can access, XSS can steal
localStorage.setItem("token", authToken)

// ✅ ALWAYS - JavaScript cannot access
cookies().set("session", authToken, {
  httpOnly: true,      // JS can't read this cookie
  secure: true,        // HTTPS only
  sameSite: "lax",     // CSRF protection
})

Vibe coding: security rules that need a human

The five manual review gates

Have a human verify these areas before production. Models often produce plausible-looking auth and payment code that fails under attack.

// Security review checklist — before deploy

□ JWT/session in httpOnly cookie (or equivalent), not localStorage
□ API routes verify auth server-side, not only middleware
□ Prices, roles, entitlements from DB — not from the client
□ User-facing errors are generic; logs hold detail
□ No secret keys exposed via NEXT_PUBLIC_
□ Input validated and sanitized on the server
□ Rate limits on auth endpoints
□ No console.log of PII in production

13a. SEO & AEO Best Practices

🟡 Intermediate | Prerequisites: Chapter 4

In the age of AI search engines (Perplexity, ChatGPT, Google's SGE), optimizing for both traditional SEO and Answer Engine Optimization (AEO) is critical.

1. Semantic HTML Structure

Use proper HTML5 semantic elements. Search engines and AI crawlers understand structure.

// ❌ BAD - Div soup
<div class="header">...</div>
<div class="content">...</div>

// ✅ GOOD - Semantic HTML
<header>...</header>
<main>
  <article>
    <section>...</section>
  </article>
</main>
<footer>...</footer>

2. Heading Hierarchy (H1 → H6)

One H1 per page. Use headings in order (don't skip H2 to H4). This creates a clear content outline.

// ✅ CORRECT STRUCTURE
<h1>Main Title</h1>
  <h2>Section</h2>
    <h3>Subsection</h3>
      <h4>Sub-subsection</h4>

3. Meta Tags (The Foundation)

4. Structured Data (Schema.org)

JSON-LD structured data helps AI engines understand your content. Use it for:

• Book/Course: Educational content
• FAQPage: Common questions (critical for AEO)
• HowTo: Step-by-step guides
• BreadcrumbList: Navigation structure

// Example: FAQPage Schema (Perfect for AEO)
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "What is Vibe Coding?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "Vibe coding is building software..."
    }
  }]
}
</script>

5. AEO-Specific Optimizations

Best Practices for AEO:

1. Answer Questions Directly: Start paragraphs with direct answers. "Vibe Coding is..." not "In this section, we'll explore..."
2. Use Q&A Format: Include FAQ sections with clear questions and concise answers.
3. Define Terms Early: Define key concepts in the first paragraph.
4. Use Lists and Tables: AI engines extract structured data easily from lists.
5. Include Context: Explain "why" not just "what". AI engines value comprehensive explanations.

6. Image Optimization

7. Performance = SEO

Google and AI engines prioritize fast-loading sites. Core Web Vitals matter:

• LCP (Largest Contentful Paint): < 2.5s
• FID (First Input Delay): < 100ms
• CLS (Cumulative Layout Shift): < 0.1

// Optimize images
<img 
  src="hero.png" 
  alt="Description"
  loading="lazy"           // Lazy load below fold
  width="1200" 
  height="630"
  decoding="async"          // Non-blocking decode
/>

// Preconnect to external domains
<link rel="preconnect" href="https://fonts.googleapis.com">

8. Mobile-First & Responsive

Mobile-first indexing is standard. Ensure your site works perfectly on mobile devices.

<meta name="viewport" content="width=device-width, initial-scale=1.0">

// Test with Chrome DevTools Mobile Emulation
// Ensure touch targets are at least 44x44px

9. Content Quality (The #1 Ranking Factor)

Content Checklist:

• ✅ Comprehensive (1000+ words for main pages)
• ✅ Original (not copied from elsewhere)
• ✅ Updated regularly (freshness signal)
• ✅ Well-structured (headings, lists, tables)
• ✅ Answers user intent (not just keywords)

10. Internal Linking

Link related content together. This helps both users and crawlers understand your site structure.

// ✅ GOOD - Contextual internal links
<p>Learn more about <a href="#prompt-engineering">Prompt Engineering</a>.</p>

// ❌ BAD - Keyword stuffing
<p>Click here for <a href="#prompt-engineering">prompt engineering prompt engineering</a>.</p>

11. robots.txt & Sitemap

Create a robots.txt file to guide crawlers:

# robots.txt
User-agent: *
Allow: /

Sitemap: https://vibecodingbible.com/sitemap.xml

Generate and submit a sitemap.xml to Google Search Console and Bing Webmaster Tools.

12. The AEO Checklist

PRO TIP: Test your AEO optimization by asking Perplexity or ChatGPT: "What is [your topic]?" If your content appears in the answer, you're doing it right.

14. Task Manager

🟢 Beginner | Prerequisites: Chapters 1-7

Build a complete task manager while learning to direct AI effectively.

Task Manager Application with Filters

Step 1: The Blueprint (Data)

First, we define what a "Task" actually is. Don't guess; tell AI.

"I want to build a Task Manager. 
First, generate a TypeScript interface for a 'Task'. 
It should have: id, title, isCompleted, createdAt, and priority (low, medium, high)."

Step 2: The Components (Tools)

Next, we build the visual pieces. Remember the LEGO analogy.

"Create a 'TaskItem' component.
Props: taking a single 'Task' object and 'onToggle' function.
Style: Use Tailwind. If priority is high, give it a red border.
Accessibility: Ensure the checkbox has an aria-label."

Step 3: The Logic (Cooking)

Now we bring it to life. This is where state lives.

"Create the main 'TaskList' component.
1. Use 'useState' to hold the array of Tasks.
2. Create a function 'toggleTask(id)' that finds the task and flips its 'isCompleted' status.
3. specific requirement: Don't mutate state directly; use .map()."

Step 4: Refinement

Finally, we polish. Ask AI to "Add a filter for Active/Completed tasks" only AFTER the basic list works.

15. Weather Dashboard

🟡 Intermediate | Prerequisites: Chapters 1-8

Weather Dashboard interacting with OpenWeatherMap API

Step 1: The Contract (Types)

Before flying, we agree on what to bring back. If we expect "temp" but get "temperature", the app crashes.

"Create a Zod schema for the Weather API response.
It should confirm that we are receiving a 'main' object with a 'temp' number, and a 'weather' array with a description string."

Step 2: The Service (Travel Agent)

Now write the function that actually travels.

"Write a function 'getWeather(city)' that fetches from the API.
1. Use the Zod schema from Step 1 to parse the response.
2. If the response is 404 (City Not Found), return null.
3. If the network fails, throw a specific 'NetworkError'."

Step 3: The View (Display)

Create the dashboard UI assuming you *already have* the data.

"Create a 'WeatherCard' component.
Props: taking a parsed 'WeatherData' object.
State: None (Pure component).
Display: Temperature in large text, description in capitalized text."

Step 4: Integration

Paste that into Cursor, Claude Code (Opus 4.8), or Codex 5.6 and iterate.

Next Step: Once you are ready for real components, use the Component Template in the Vibe Library.

"Create the main Page.
1. Add a Search Input.
2. When the form submits, call 'getWeather'.
3. While waiting, show a 'SkeletonLoader' (Optimistic UI).
4. If 'getWeather' throws, show a red Error Banner."

16. E-commerce Page

🔴 Advanced | Prerequisites: All previous chapters

Product Page with specialized variant selection

Step 1: The Product Model

We need a data structure that allows for "Product" (the parent) and "Variants" (the children).

"Create 3 interfaces:
1. Product (id, title, basePrice)
2. Variant (color, size, sku, stockLevel)
3. CartItem (product + selected variant + quantity)"

Step 2: The Global Cart (Context)

The Cart is like a physical shopping cart that follows you around the store.

"Create a 'CartProvider' using Zustand.
1. persist: Save to localStorage automatically.
2. actions: addItem, removeItem, updateQuantity.
3. logic: If adding same SKU, increment quantity, do not duplicate item."

Step 3: The Product Page Strategy

Now build the page where the decision happens.

"Create a 'ProductConfigurator' component.
Props: product and all variants.
1. User selects Color -> Filter available sizes.
2. User selects Size -> Calculate final price and stock status.
3. If variant is OOS -> Disable 'Add to Cart'."

Step 4: Performance Guardrails

E-commerce is heavy on images. Slow images = lost sales.

"Optimize the product page:
1. Use next/image with 'priority' on the main hero image.
2. Use 'sizes' prop to serve smaller images on mobile.
3. Memoize the variant calculation function so it doesn't run on every render."