Vibe Coding Mastery

The complete operating system for building software with AI. From first prompt to production deployment — prompting frameworks, architecture patterns, testing strategies, debugging playbooks, and production graduation checklists. Works with Claude Code, Cursor, Windsurf, Copilot, and any AI coding tool.

# Vibe Coding Mastery

The complete system for building software with AI — from zero to production. Not tips. Not theory. A full operating methodology.

**What is vibe coding?** Programming where you describe what you want and let AI generate code. You evaluate by results, not by reading every line. Coined by Andrej Karpathy (Feb 2025).

**Key distinction (Simon Willison):** If you review, test, and explain the code — that's AI-assisted software development. Vibe coding means accepting AI output without fully understanding every function. This skill covers both modes and the spectrum between them.

---

## Phase 1: When to Vibe (Decision Matrix)

Before starting, classify your project:

| Factor | Vibe ✅ | Don't Vibe ❌ |
|--------|---------|---------------|
| **Stakes** | Low (prototype, internal, learning) | High (payments, auth, compliance) |
| **Timeline** | Hours to days | Months+ |
| **Team size** | Solo or pair | Large team with standards |
| **Domain knowledge** | You understand the domain | Unfamiliar territory |
| **Reversibility** | Easy to rewrite | Hard to change later |
| **Data sensitivity** | Public/test data | PII, financial, health |

**Scoring:** Count ✅ checks.
- 5-6: Full vibe mode. Ship fast.
- 3-4: Vibe with guardrails. Review critical paths.
- 1-2: AI-assisted development, not vibe coding. Review everything.
- 0: Write it yourself or hire someone who understands the domain.

### Vibe Coding Maturity Levels

| Level | Description | Who |
|-------|-------------|-----|
| **L1 — Passenger** | Copy-paste AI output, hope it works | Beginners |
| **L2 — Navigator** | Guide AI with context, catch obvious errors | Intermediate |
| **L3 — Pilot** | Architecture decisions, AI implements, you review | Experienced devs |
| **L4 — Conductor** | Orchestrate multiple AI sessions, parallel streams | Power users |

**Target: L3 minimum for anything going to production.**

---

## Phase 2: Tool Selection

### Primary Tools Matrix

| Tool | Best For | Context Window | Multi-file | Terminal | Cost |
|------|----------|---------------|------------|----------|------|
| **Claude Code** | Full-stack, complex refactors, CLI | 200K | Excellent | Native | API usage |
| **Cursor** | Editor-integrated, rapid iteration | 128K | Good | Via terminal | $20/mo + API |
| **Windsurf** | Beginner-friendly, guided flows | 128K | Good | Limited | $10/mo + API |
| **GitHub Copilot** | Inline completions, small edits | 8-32K | Limited | No | $10-19/mo |
| **Aider** | Git-aware, open source, CLI | Varies | Good | Native | API only |
| **Cline (VS Code)** | VS Code native, plan mode | Varies | Good | Via terminal | API only |

### Multi-Tool Strategy

Use tools in combination:
1. **Architecture & planning** → Claude Code or Claude chat (largest context, best reasoning)
2. **Implementation** → Cursor or Claude Code (fast iteration, multi-file edits)
3. **Quick fixes & completions** → Copilot (inline, zero friction)
4. **Code review** → Claude chat (paste diffs, get thorough review)

---

## Phase 3: Rules Files (Your Persistent Context)

Rules files teach AI your conventions once. Without them, every session starts from zero.

### Universal Rules File Template

```markdown
# Project Rules

## Stack
- Language: [TypeScript/Python/Go/etc.]
- Framework: [Next.js/FastAPI/etc.]
- Database: [PostgreSQL/SQLite/etc.]
- Styling: [Tailwind/CSS Modules/etc.]
- Package manager: [pnpm/npm/poetry/etc.]

## Code Style
- Max function length: 50 lines
- Max file length: 300 lines
- One export per file (prefer)
- Use [const/let, never var] / [type hints always]
- Error handling: [explicit try/catch, never swallow errors]
- Naming: [camelCase functions, PascalCase components, UPPER_SNAKE constants]

## Architecture
- File structure: [describe or reference]
- API pattern: [REST/tRPC/GraphQL]
- State management: [Zustand/Redux/signals/etc.]
- Auth pattern: [JWT/session/OAuth provider]

## Testing
- Framework: [Vitest/Jest/Pytest/etc.]
- Minimum coverage: [80%/90%/etc.]
- Test file location: [co-located/__tests__/tests/]
- Run before committing: [command]

## Do NOT
- Do not use `any` type in TypeScript
- Do not install new dependencies without asking
- Do not modify database schema without migration
- Do not hardcode secrets, URLs, or config values
- Do not remove existing tests

## When Unsure
- Ask before making architectural decisions
- Show the plan before implementing changes >100 lines
- Flag security-adjacent code for manual review
```

### Where to Put It

| Tool | File | Notes |
|------|------|-------|
| Claude Code | `CLAUDE.md` in repo root | Also reads .claude/ directory |
| Cursor | `.cursor/rules/*.mdc` | Supports conditional rules with globs |
| Windsurf | `.windsurfrules` in repo root | Single file |
| Aider | `.aider.conf.yml` + conventions in chat | YAML config + initial prompt |
| Generic | `AGENTS.md` or `CONVENTIONS.md` | Any tool can be told to read it |

### Cursor Conditional Rules (.mdc)

```markdown
---
description: React component standards
globs: src/components/**/*.tsx
alwaysApply: false
---

# Component Rules
- Functional components only (no class components)
- Props interface above component, named [Component]Props
- Use forwardRef for components that accept ref
- Co-locate styles in [component].module.css
- Co-locate tests in [component].test.tsx
- Export component as named export, not default
```

### Rules File Quality Checklist

- [ ] Stack and versions specified
- [ ] File/function size limits defined
- [ ] Naming conventions documented
- [ ] "Do NOT" section with common AI mistakes
- [ ] Testing expectations clear
- [ ] Architecture patterns described or referenced
- [ ] Security-sensitive areas flagged
- [ ] Dependencies policy stated

---

## Phase 4: Prompt Engineering for Code

### The 5-Level Prompt Quality Hierarchy

**Level 1 — Wish (bad)**
> "Build a todo app"

**Level 2 — Request (okay)**
> "Build a todo app with React and Tailwind"

**Level 3 — Specification (good)**
> "Build a todo app: React 18, TypeScript, Tailwind. Features: add/edit/delete/toggle todos. Store in localStorage. Responsive. Under 200 lines total."

**Level 4 — Brief (great)**
> "Build a todo app. Here's the spec:
> - Stack: React 18 + TS + Tailwind + Vite
> - Features: CRUD todos, toggle complete, filter (all/active/done), persist to localStorage
> - Constraints: Single component file, under 200 lines, no external deps beyond stack
> - Done when: All features work, page refresh preserves state, mobile responsive
> - Start with the data types, then build up."

**Level 5 — Contract (production-grade)**
```yaml
task: Todo application
stack:
  runtime: React 18 + TypeScript strict
  styling: Tailwind CSS 3.x
  build: Vite 5
  test: Vitest + Testing Library
features:
  - CRUD operations on todos
  - Toggle completion status
  - Filter: all | active | completed
  - Bulk actions: complete all, clear completed
  - Persist to localStorage with versioned schema
constraints:
  - Max 3 component files
  - Max 200 lines per file
  - No external state management library
  - Keyboard accessible (tab, enter, escape)
  - Mobile responsive (min 320px)
acceptance:
  - All features functional
  - Page refresh preserves state
  - 90%+ test coverage
  - No TypeScript errors (strict mode)
  - Lighthouse accessibility score > 90
approach: Start with types/interfaces, then hooks, then components, then tests.
```

### 12 Proven Prompt Patterns

1. **Scaffolding**: "Create the project structure with empty files and type definitions. Don't implement yet."
2. **Incremental**: "Implement only [specific function]. Don't touch other files."
3. **Explain-then-build**: "Explain how you'd architect this, then implement after I approve."
4. **Test-first**: "Write the tests first based on these requirements. Then implement to make them pass."
5. **Refactor**: "Refactor [file] to [goal]. Keep the same behavior. Don't add features."
6. **Debug**: [paste error] "This happens when [action]. Expected [behavior]. The