Vibe Coding Starts With the Spec: Prompt Discipline That Prevents Rework

The short answer: The most expensive vibe-coding mistake isn't buggy code — it's the agent confidently building the wrong thing fast because your prompt was vague. An AI agent fills ambiguity with the most common pattern it has seen, not with your actual requirement. So the leverage is on the input side: write the spec and acceptance criteria before the agent starts, give it constraints and non-goals, break the ask into verifiable steps, and iterate the spec rather than patching the code. A vague prompt is a guarantee of rework.

I've watched this happen more times than I'd like to admit — mine included. You type a one-liner, the agent produces three hundred lines in twenty seconds, the demo runs, and then you realize it built a thing adjacent to what you meant. Now you're not reviewing code, you're archaeology-ing someone else's assumptions out of a diff. The speed was real. It just ran in the wrong direction.

A vague prompt has too many right answers

Here's the thing people miss about these agents: they're not bad at following instructions. They're excellent at following whatever instructions you actually gave, including the ones you didn't mean to give by leaving them out. "Add a login form" is not one task. It's a family of tasks — email or username, password rules, server-side validation or not, which library, which styling, where state lives — and the agent will pick one member of that family, commit to it hard, and build fast.

The mistake is treating the prompt like a wish and the agent like a genie. It's closer to handing a ticket to a fast, literal contractor who never asks a clarifying question. If the ticket is ambiguous, you don't get a question back — you get a confident wrong build.

Write the spec before the agent starts

The single highest-leverage habit: spend two minutes writing acceptance criteria before you prompt. Not a document — just the constraints that pin down which of the many valid builds you actually want. Stack and conventions. Non-goals (the things you explicitly do not want it to touch). A concrete example of the input and the expected output. The edge cases you already know will bite. What "done" looks like, stated as something checkable.

The vague version is a coin flip you'll pay for later. The specified version has essentially one correct implementation, and — this is the part that compounds — it ships with its own acceptance test baked into the prompt. The agent now knows when it's finished, and so do you.

Break big asks into verifiable steps

The spec discipline scales down as well as up. A large ask ("build the checkout flow") produces a large diff, and a large diff hides the one place the agent diverged. Break it into steps you can each check: the data layer first, verify it; the API next, verify it; the UI last. Each step has its own tiny acceptance criterion, each one is reviewable in isolation, and when something's off you know exactly which step to re-run instead of re-reading the whole thing.

This is the same reason a good estimate is a range with named assumptions rather than a single confident number — see why your estimates are always wrong. A spec and an estimate are the same move: make the uncertainty explicit before you commit, so reality has fewer ways to surprise you.

Iterate the spec, not just the code

When the agent gets it wrong, the instinct is to patch the output: "no, change this line." Resist it past the first round. If you're correcting the same class of thing twice, the spec was underspecified — fix that and regenerate. Patching the code teaches you nothing reusable; tightening the spec gives you a prompt you can run again, hand to a teammate, or feed to the next agent. Treat the spec as the durable artifact and the code as its disposable output.

Use agents and skills deliberately

The irony of spec discipline is that an agent can help you with it — you just have to point a different kind of agent at the problem before you write a line of feature code:

• A product-manager / PRD skill to turn a fuzzy "I want X" into functional requirements, non-goals, and acceptance criteria. This is the exact step a general-purpose coding agent skips, and it's where most vibe-coding rework is born.
• An api-and-interface-design skill when the ask crosses a boundary (a new endpoint, a shared module), so the contract is pinned down in the spec before any client depends on it.
• A coding-standards skill to encode your conventions once, so "match our style" stops being a thing you re-type into every prompt.

The meta-point holds here as everywhere in this cluster: a specialized agent that defines or reviews the work catches the exact class of mistake a generalist agent makes when it's left to guess. Spec-first isn't slower. It's the difference between leverage and a fast wrong turn — the same shift I wrote about in the year coding agents stopped being a novelty and six months of AI coding tools: what actually stuck.

This is one of the vibe-coding deep-dives — start from the vibe-coding precautions overview. Get the input side right and the other precautions get easier, because an agent that knows exactly what you asked for has far fewer chances to quietly build the wrong thing.