Spec-First Vibe Coding: Write the PRD Before the Prompt

Spec-first vibe coding means writing a short, structured product spec before you open an AI coding tool, then feeding the model that spec instead of an off-the-cuff prompt. The spec does not need to be a formal PRD with sign-offs and stakeholders; it needs to nail down the intent, constraints, and shape of the output so the model is generating against something durable rather than guessing at what you meant. This guide walks through why that ordering matters, how to write a spec that is actually useful for an AI agent (not just a human reviewer), and how to carry it through from prompt to shipped code.

What Vibe Coding Gets Right, and Where It Breaks Down

Vibe coding, in the loose sense the term has taken on, means describing what you want in natural language and letting an AI agent write, run, and iterate on the code, often without reading every line it produces. This is not inherently reckless. Modern coding agents are genuinely good at translating intent into working code, and for prototypes, internal tools, and greenfield features, iterating by conversation is often faster than writing every function by hand. The problem is not the technique; it is what most people skip before they start typing.

A raw prompt is a compressed, ambiguous stand-in for a decision you have not fully made yet. When you type "build a pricing page with three tiers" into an agent, you are letting the model fill in dozens of decisions you did not think to specify: what happens on mobile, whether the middle tier is highlighted, what the currency formatting looks like, whether there is an annual/monthly toggle, what the empty and error states look like. The agent will confidently pick something for each of those, and if you did not decide first, you will not notice until three prompts later when the whole layout has to be reworked because an assumption baked in early turned out wrong.

This is the actual failure mode behind most "vibe coding produced a mess" stories: not that the AI wrote bad code, but that nobody wrote down the spec, so the AI had to invent one on the fly, and that invented spec drifted further from the real requirement with every follow-up prompt. Spec-first vibe coding fixes the ordering. You make the decisions once, in a form both you and the model can refer back to, and every prompt after that is an instruction to implement the spec rather than a new opportunity to reinterpret the goal.

The Core Idea: Write the Spec, Then Vibe

The workflow has three phases, and the discipline is in not skipping the first one, even when it feels slower than just prompting.

1. Spec. Write a short, plain-language document that pins down intent, constraints, inputs/outputs, and what "done" looks like. This is the artifact that survives across sessions, models, and tools.
2. Prompt. Turn the spec into concrete instructions for the agent, referencing the spec directly rather than re-explaining the feature from memory.
3. Verify. Check the output against the spec's acceptance criteria, not against a vague sense of whether it "looks right."

Each phase catches a different class of mistake. The spec phase catches ambiguity before any code exists, which is the cheapest place to catch it. The prompt phase catches translation errors, where you know what you want but describe it imprecisely. The verify phase catches drift, where the agent quietly reinterpreted something over the course of a long session. Skipping the spec phase does not just risk one failure mode; it removes your ability to catch any of them, because there is no fixed reference point to compare the output against.

How to Write a Spec an AI Agent Can Actually Use

A spec written for an AI coding agent is not the same document as a PRD written for a product review meeting. It needs less narrative and more explicit, checkable detail. Aim for something you could paste directly into a coding tool's context window and have it make sense without a live human filling in gaps. In practice this means five sections, each answering a question the model would otherwise have to guess.

1. Intent: what problem this solves, in one paragraph

State the user-facing problem before the solution. "Users abandon checkout because they can't see shipping cost until the final step" is a spec an agent can reason about; "add a shipping estimator" is just a feature name. When the model understands the underlying intent, it makes better calls on the dozens of small decisions a spec can never fully enumerate, because it can ask "does this choice serve the stated problem" instead of guessing blind.

2. Constraints: what must stay true

List the non-negotiables explicitly: which framework, which existing components to reuse rather than reinvent, performance or accessibility bars, design tokens or a design system that must be respected, browser or device support. Constraints are the single highest-leverage section in the whole spec, because an agent with no stated constraints will happily introduce a new state-management library, a new color palette, or a new folder convention that nobody asked for and that someone now has to unwind.

3. Inputs and outputs: the concrete shape

Describe the data going in and the result coming out as specifically as you can: the shape of an API response, the props a component accepts, the states a UI element can be in (empty, loading, error, populated, zero-results). If you already know the exact interface, write it as a type or schema rather than prose — a model can implement against a TypeScript interface far more reliably than against an adjective.

4. Explicit non-goals

This is the section most specs skip and the one that saves the most rework. Say plainly what you are not asking for in this pass: "no dark mode yet," "do not touch the checkout flow," "styling only, no backend changes." Agents are eager to be helpful, and an unscoped agent will frequently do more than you asked, refactor adjacent code "while it's in there," or add a feature you didn't request because it seemed like a natural extension. A non-goals list is the cheapest guardrail you can add.

5. Acceptance criteria: how you will know it's done

Write these as a short checklist of testable statements, not a feeling. "The form submits with a single required field" is checkable. "The form should feel clean and simple" is not. Where you can, phrase acceptance criteria as things a human or an automated test can verify by looking at the running result, since that is also what you will hand the agent to self-check against before you review.

Turning the Spec Into a Prompt

Once the spec exists, the prompt's job shrinks considerably: it points the agent at the spec and tells it what to do with it, rather than re-deriving the requirement from scratch. A useful pattern is to paste the spec into the agent's context (or keep it as a file the agent can read) and then issue a short, direct instruction: implement section three of this spec, respecting the constraints in section two, and stop once the acceptance criteria in section five pass. This keeps the prompt itself simple and disposable — you can rephrase it, retry it, or hand it to a different model entirely, and the spec underneath stays the stable source of truth.

This separation also solves a subtler problem with long agent sessions: context drift. As a conversation with a coding agent grows, earlier decisions get pushed further back in the context window and start competing with everything that has happened since. A spec that lives as a standalone artifact — a file in the repo, a pinned note, a linked doc — is something you can re-paste or re-reference at any point in a long session to pull the agent back to the original intent, instead of hoping it remembers a decision from forty turns ago.

Where Design Specs Fit In

For UI-heavy work, the spec is often stronger when it includes a visual reference alongside the prose, because "make it look modern" is exactly the kind of instruction an agent has to guess at, while a concrete layout removes the guesswork. This is one of the more underrated uses of a well-structured Figma file in an AI-assisted workflow: a kit with named layers, consistent spacing tokens, and clearly separated components functions as a visual spec that a design-to-code agent can read far more reliably than it can read adjectives. If you are building out a storefront or admin surface and want that kind of ready-made visual spec to prompt against rather than designing from a blank canvas, our Figma UI kits are built with exactly that structure in mind — consistent component naming and spacing so the intent transfers cleanly whether a human or an agent is the one implementing it.

The same logic applies in reverse when you are working from an existing Shopify theme or storefront and want an agent to extend it consistently: point it at the existing component patterns and design tokens as part of the constraints section, rather than letting it invent a new visual language for the one new page you asked for.

Tooling Notes: Context, MCP, and Keeping Specs Close to the Code

A growing set of tools exist specifically to keep specs and code in sync rather than letting the spec live in a separate doc that quietly goes stale. The Model Context Protocol (MCP) is worth understanding here even if you are not building agent integrations yourself: it standardizes how an AI tool pulls in context — files, design data, project state — from outside its own chat window, which is exactly the mechanism that lets a spec file, a linked design system, or a project's existing conventions get surfaced to the model automatically instead of you re-pasting them every session. Coding-agent products like Claude Code and Cursor increasingly support exactly this pattern: a project-level instructions file the agent reads before every session, plus on-demand access to more specific specs or design references when a task calls for them.

Whether or not your toolchain has MCP wired up, the underlying habit is the same and works with nothing more than a markdown file: keep one spec per meaningful unit of work, store it next to the code it describes, and update it when the real requirement changes rather than letting the prompt history become the only record of what was actually decided. A spec that lives only inside a chat transcript is nearly as fragile as no spec at all, because nobody will scroll back through forty prompts to find the one line that mattered.

Common Failure Modes This Workflow Prevents

A few patterns show up repeatedly in teams that adopt AI coding tools without a spec-first habit, and each has a specific, boring fix.

• Scope creep from an eager agent. Fixed by an explicit non-goals section, restated in the prompt.
• Silent architectural drift (a new state library, a new folder pattern, a new naming convention appearing mid-project). Fixed by a constraints section that names the existing patterns to reuse.
• "Looks right" acceptance that later turns out wrong. Fixed by checkable acceptance criteria instead of a subjective once-over.
• Late-session context loss where the agent forgets an early decision. Fixed by keeping the spec as a standalone, re-referenceable artifact rather than only inside the chat history.
• Rework from ambiguous UI direction. Fixed by attaching a concrete visual reference — a design file, a screenshot, an existing component — instead of describing appearance in adjectives.

A Practical Spec Template You Can Reuse

You do not need special tooling to start. A plain markdown file with five headers, filled in honestly before you open your coding agent, is enough to change the outcome of most sessions.

• Intent — one paragraph: what user problem this solves and why it matters now.
• Constraints — bullet list: framework, existing components/design tokens to reuse, performance/accessibility bars, anything that must not change.
• Inputs/outputs — concrete shapes: data schema, component props, UI states (empty, loading, error, populated).
• Non-goals — bullet list: what is explicitly out of scope for this pass.
• Acceptance criteria — a short checklist of testable statements describing done.

Write it before the first prompt, keep it in the repo alongside the feature it describes, and update it — not just the prompt — when the requirement changes. Everything else about vibe coding, including the parts that are genuinely fast and genuinely fun, works better once this one habit is in place. For more on how we think about building UI systems that hold up under both human and AI-assisted development, see our other posts on the Polo Themes blog.

Frequently Asked Questions

Isn't writing a spec just slower than prompting directly?

It adds time up front and saves more time later. A five-minute spec that prevents two or three rounds of "actually, not like that" rework is a net time saver, and the gap widens the more complex or ambiguous the feature is. For truly trivial, throwaway prompts, a full spec is overkill; the discipline matters most for anything you intend to keep.

Does this only apply to Claude Code or Cursor, or does it work with any AI coding tool?

The workflow is tool-agnostic. Any agent that accepts a text prompt can be pointed at a spec file or have one pasted into its context. Tools with native project-context support (via MCP or an equivalent mechanism) make it easier to keep the spec persistently available, but the underlying habit of writing the spec first works with any model or interface.

What is the difference between this and a traditional PRD?

A traditional PRD is often written for stakeholder alignment and includes business context, timelines, and success metrics aimed at humans. A spec-first vibe coding document is leaner and aimed at an implementer, human or AI: it prioritizes explicit constraints, concrete input/output shapes, and checkable acceptance criteria over narrative and business framing. Many teams keep both, with the lightweight spec derived from the PRD right before implementation starts.

Should design specs (Figma files, mockups) replace a written spec?

They complement each other rather than replace one another. A visual reference removes ambiguity about layout and appearance, but it rarely encodes constraints, non-goals, or acceptance criteria on its own. The strongest combination is a written spec that references a concrete design file for the parts that are easier to show than to describe.