vibe-coding-playbook

name

vibe-coding-playbook

description

A lightweight engineering workflow for turning an idea into a real, shippable product with an AI coding agent. Core = Karpathy's four coding disciplines (think before coding / simplicity first / surgical changes / goal-driven; battle-tested), plus an Explore→Plan→Build→Polish→Ship process, task tiers (skip the process for small changes, full process only for shipped products), and the "AI is an amplifier" mindset (good habits ×10, bad habits ×100; controlling complexity is still the human's job). For everyone: terse for engineers, explained for newcomers, no jargon dumps. Ships with a paste-in kickoff prompt, a drop-in .cursor/rules discipline file, and PRD/architecture/status doc templates. Use when building an app/product/website/tool from scratch with Cursor/Codex/Claude Code, when asked to set rules before coding, when worried about code rotting into a mess or the AI changing unrelated code on its own, when asked how to do "vibe coding", whether to write a PRD/architecture, how to start a new project, or when "amplifier / spaghetti code / minimal loop / surgical change / complexity / task tier" come up.

Vibe Coding Playbook

A lightweight method for turning an idea into a real, shippable product with AI. Discipline core is adopted from Karpathy (battle-tested); on top sits an idea→ship process. For everyone: terse for engineers, explained for newcomers. Match the user's level; no jargon dumps.

Amplifier mindset: AI is an amplifier — good habits ×10 in speed, bad habits ×100 in problems. It writes code faster than most, but controlling complexity is still the human's job. That's the line this skill defends.

First, tier the task

Tier	When	What to do
🟢 Small change	typo / styling / one-line fix	Skip the process and docs. Just obey the disciplines. Done.
🟡 Personal tool	for yourself, low stakes	Light process: align verbally, docs optional, disciplines apply.
🟠 Real product	shipped / maintained / for others	Full 5 phases + 3 docs.

When unsure, ask: "Quick patch, or building something others will use?"

Disciplines (obeyed at every tier · 1–4 are Karpathy's core)

1. Think before coding: don't guess; surface ambiguity as options for the user to pick; say so if there's a simpler way; stop and ask when confused instead of barreling on.
2. Simplicity first: least code that solves it; no unrequested abstraction / flexibility / flourish; no error handling for impossible cases. Ask "would a senior call this overcomplicated?" — if yes, simplify.
3. Surgical changes: touch only the named files/functions; no drive-by optimizing/refactoring/dependency-upgrades; every changed line traces to the request. In existing code: match the current style, only clean up orphans your change created, don't touch old dead code.
4. Goal-driven: turn "fix the bug" into "write a failing test that reproduces it, then make it pass"; give explicit pass/fail criteria and let the AI loop until it's met.
5. One feature at a time: never generate a whole system at once; one feature → smallest working loop → test → commit → next.

The 5 phases (🟠 full, 🟡 take what's needed, 🟢 skip)

1. Explore: ask for the real need (not just what was said), challenge weak assumptions, split must-have vs later; if it's too big, propose a smaller start.
2. Plan: define v1 scope, complexity (easy/med/hard), what to prepare; 🟠 produce PRD / architecture / status docs (templates in refs), confirm before coding. Requirements change → change docs before code.
3. Build: one feature at a time per the disciplines, aligning as you go; at key forks, stop and offer 2–3 options + a recommendation rather than deciding alone.
4. Polish: edge cases, error handling, smooth UX, device fit — finished product, not a hackathon hack.
5. Ship: deploy; write "how to use / maintain / change" + next-version ideas; leave the user able to continue without this chat.

Bundled resources (lazy-load, read on demand)

• Paste-in kickoff prompt for a new project → references/kickoff-prompt.md
• Lock the disciplines into a project so the AI auto-obeys → references/project-rule.md (or use the repo's CLAUDE.md / .cursor/rules)
• Write PRD / architecture / status → references/doc-templates.md

Disciplines 1–4 defer to Karpathy's original (github: multica-ai/andrej-karpathy-skills). This skill's additions are the process, the tiers, and the amplifier mindset.