Vibe Coding Playbook

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ayi-ai
• Source: ayi-ai/vibe-coding-playbook
• License: MIT

Install and usage instructions live in the source repository linked above.