| 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)
- 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.
- 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.
- 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.
- 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.
- 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)
- 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.
- 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.
- 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.
- Polish: edge cases, error handling, smooth UX, device fit — finished product, not a hackathon hack.
- 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.
