The popular advice is to stop vibe coding and start writing specifications. That's too blunt. A disposable prototype doesn't need the same process as a checkout migration, and writing a document doesn't make generated code safe. The useful distinction is what you're allowed to do with the output, and what evidence you need before other people depend on it.
For a small product team, spec driven development vs vibe coding is an operating decision, not an ideological one. Explore conversationally when you're still discovering the product. Require explicit contracts before production, then measure whether the additional planning reduces review effort and rework.
Table of Contents
- Spec Driven and Vibe Coding at a Glance
- How Each Workflow Moves from Idea to Merge
- What a Working Spec Contains
- Where Verification Separates the Two Workflows
- Speed, Quality and Hidden Review Costs
- When Vibe Coding Earns Its Place
- Combining Both Workflows and Choosing a Default
Spec Driven and Vibe Coding at a Glance
Spec driven development starts with an agreed target. Vibe coding starts with an intent you refine by trying the output. Both can use the same coding agent, editor, and deployment tools. The difference is when the team makes requirements explicit and when it checks them.
Core criteria compared side by side
| Criterion | Spec Driven Development | Vibe Coding |
|---|---|---|
| Starting point | Written spec with goals, constraints and acceptance criteria | Natural-language intent refined through prompts |
| Where verification happens | Checks are defined before implementation, then enforced through tests and review checkpoints | After generation, by running the output and iterating |
| Speed to first prototype | Slower initially because requirements are written first | Fast for bounded experiments, potentially within a working session |
| Traceability of decisions | High when requirements, tests and code are linked | Low when decisions remain only in chat history |
| Typical failure mode | Specs that restate the prompt without testable criteria | Implicit requirements and unverified broad changes |
| Best fit | Production features, shared systems and regulated work | Exploration, prototypes, UI mockups and internal experiments |
The term vibe coding, introduced by Andrej Karpathy in February 2025, describes conversational iteration that can involve accepting code without fully understanding its internal logic, according to this ACM paper on the workflow. That's narrower than AI-assisted programming. Asking an agent to implement a reviewed interface contract isn't the same working method as prompting until a screen looks right.
The practical difference is the review target
Say you ask an agent to add team invitations. A conversational prototype might produce an invitation form, an email preview, and a successful acceptance screen. That's enough to discuss the interaction with a designer.
A production specification needs to settle whether invitations expire, who can issue them, what happens when an account already exists, and whether acceptance grants access immediately. Those decisions determine behavior that a happy-path demo won't expose.
Neither approach removes engineering judgement. Specification work can become ceremony, while conversational work can conceal consequential assumptions.
Practical rule: Use vibe coding to learn what should exist. Use specification-driven work when customers or other teams will depend on its behavior.
How Each Workflow Moves from Idea to Merge
The spec-driven path separates product decisions from implementation decisions. That separation gives reviewers a chance to reject the wrong behavior before an agent builds an elaborate version of it.
The spec-driven path
-
Write the problem, goals and non-goals. Keep the opening brief enough to read during a kickoff. Explain the user problem and explicitly exclude adjacent work, such as redesigning account management while adding invitations.
-
Define interfaces, data rules and testable acceptance criteria. Specify request and response shapes, authorization boundaries, and failure behavior so the agent doesn't invent product policy while choosing implementation details.
-
Assign unresolved decisions to owners. An open question about invitation expiry belongs to someone who can make that decision. Mark whether it blocks implementation or can remain configurable.
-
Ask the agent for an implementation plan before asking for code. Review affected modules, dependencies, migrations, and proposed tests, particularly anything outside the intended change boundary.
-
Generate small slices tied to acceptance criteria. Implement invitation creation separately from acceptance and revocation. Focused diffs let reviewers inspect behavior without reconstructing an entire feature from a broad patch.
-
Run the checks and review against the specification before merge. Resolve discrepancies by changing either the implementation or the agreed requirement, not by accepting whichever behavior the agent happened to produce.
The process is easier to maintain when it's part of the team's normal AI coding workflow, rather than a separate documentation exercise.
This flow summarizes the progression from agreement to merge.

The conversational loop
Vibe coding follows a shorter loop: describe the feature, generate it, run it, paste the error back, and repeat until the behavior looks right. For discovery, that direct feedback can be more useful than debating requirements nobody has tested with users.
The breakdown often starts when another feature changes the original one. Add invitation revocation, for example, and the agent may adjust shared authorization logic without preserving the assumptions behind acceptance.
The spec-driven path breaks differently. If the team approves a vague contract or lets it become stale, reviewers can confidently validate the wrong target.
The early steps are where specification work consumes time. The intended payback comes during review, when people can evaluate a bounded change against agreed behavior instead of reopening product decisions inside a pull request.
What a Working Spec Contains
A working spec is an agreement a reviewer can challenge and a test can check. It shouldn't read like an expanded prompt with more adjectives.
For ordinary production changes, I'd aim for a compact document with the following contents. Keep schemas and detailed test fixtures alongside it rather than burying the decision-making in a large attachment.
A reusable production template
-
Problem, goals and non-goals. Describe the user outcome and the boundaries of the change. If checkout repricing is in scope but discount policy isn't, say so.
-
Interface contracts. Name endpoints, input and output shapes, error responses, and compatibility expectations. For an existing API, identify what callers must not need to change.
-
Acceptance criteria. Write observable behavior using given, when, then statements. For example: given a saved cart with an expired price, when the customer checks out, then the system re-prices the cart and shows the new total before payment.
-
Non-functional rules. Record the latency budget, permitted dependencies, data retention rules, and security requirements. Replace vague instructions such as secure storage with the actual access and handling constraints.
-
Open questions. Give each question a named owner and a due date. Distinguish a blocking decision from a detail the implementer can choose.
-
Completion evidence. Name the automated tests, manual checks, or recorded user validations that demonstrate each criterion. Include who accepts evidence that can't be automated.
Make the document usable
Treat this as part of product requirements management, not a file the agent generates and nobody reviews. Product should own intended behavior, engineering should challenge feasibility and interfaces, and the implementer should identify missing cases.
A specification fails when two reviewers can read it and still disagree about whether the feature is finished.
Keep the main document short enough that people will update it during a change. Precision matters more than document length.
Where Verification Separates the Two Workflows
Verification timing is the operational difference. In a spec-driven workflow, the team defines acceptance tests, architecture constraints, and review checkpoints before implementation. In an unconstrained conversational workflow, formal checking often begins only after the feature appears to work.
The ViBench study classified failures in vibe-coding trajectories across implementation (30.1%), tooling (27.6%), end-to-end verification (26.2%), and specification (15.6%). These are benchmark findings from one study, not universal failure rates for product teams.
Where vibe-coding failures occurred in one benchmark
| Failure location | Share of failures |
|---|---|
| Implementation | 30.1% |
| Tooling | 27.6% |
| End-to-end verification | 26.2% |
| Specification | 15.6% |
The specification category matters. A written requirement can be incomplete, contradictory, or wrong, so moving verification earlier doesn't eliminate the need to challenge the requirement itself.
Establish a spec gate before merge
Require every generated feature to map to explicit requirements, verification evidence, and recorded assumptions. The pull request should let a reviewer answer what behavior changed, why it changed, and how the team checked it.
Use requirement coverage as the primary gate metric: the percentage of acceptance criteria linked to automated tests or manually verified evidence. A checkbox saying tests pass isn't a mapping. Identify the criterion and the test or observation that proves it.
For checkout repricing, evidence might include a contract test for the updated total, an integration test confirming that payment uses that total, and a manual check that the customer sees the change before confirming. Each check addresses a different claim.
A practical approach to testing AI-generated code should also include negative paths and existing behavior outside the feature's happy path.
Don't confuse coverage with adequacy
An agent can write a test that confirms its own mistaken assumption. Have a human review important assertions against the intended behavior, especially authorization, destructive actions, and recovery after partial failure.
Track rework rate and time from agreed requirement to first passing end-to-end test alongside requirement coverage. Those measures help reveal whether the team is resolving uncertainty before implementation or repeatedly discovering it afterward.
Keep unresolved assumptions visible at merge. A deliberately deferred visual polish decision is different from an unanswered question about who can access customer records.
Speed, Quality and Hidden Review Costs
AI assistance has a credible productivity case. An analysis combining three experiments and 4,867 developers estimated a 26.08% increase in completed tasks with a coding assistant, with a standard error of 10.3%, as described in A History of Vibe Coding.
That result concerns coding-assistant use, not a controlled comparison proving that unconstrained vibe coding outperforms specification-driven work. It doesn't establish whether requirements were complete, behavior matched stakeholder intent, or defects appeared after release.
Passing tests isn't the whole quality target
A quantitative study of AI-generated code quality found no direct correlation between functional pass@1 performance and the broader quality and security of code that passed those functional tests. A function can return the expected result while still containing maintainability or security problems.
Use layered checks rather than treating unit-test success as permission to merge. Contract and integration tests check boundaries and interactions; static analysis flags maintainability concerns; dependency and secret scanning inspect different security risks.
Review time goes into work generation doesn't perform for you: understanding unfamiliar abstractions, checking whether a dependency was necessary, reconstructing changed behavior, and verifying that tests assert the right thing. When an agent modifies unrelated modules, reviewers also have to separate necessary changes from incidental cleanup.
The measurement model needs to include those activities, not just generated output.

Measure accepted work and its downstream cost
Use a lightweight checklist attached to the issue and pull request:
- Median time to accepted feature: Measure from an agreed requirement to acceptance against its criteria, including planning, review, and fixes.
- Review effort and iterations: Record reviewer time and substantive rounds of requested changes. Separate product clarification from implementation correction.
- Rework rate: Track the share of implementation effort spent correcting or replacing work because it missed agreed behavior.
- First passing end-to-end test: Record elapsed time from requirement agreement to the first successful test across the complete workflow.
- Defect density and escaped defects: Use a consistent code-size denominator for confirmed defects, and separately identify defects discovered after release.
- Rollback frequency: Record releases reverted because the change wasn't safe or correct, with the reason attached.
Compare similar work types. A copy experiment and a schema migration shouldn't share a productivity baseline merely because both closed a ticket.
Also inspect where engineers spend remediation time. Missing acceptance criteria call for better product clarification; unnecessary abstractions call for tighter implementation constraints; slow reviews may call for smaller diffs rather than longer specs.
Measurement rule: Count a feature as fast when the team accepts it safely, not when the agent first produces code.
When Vibe Coding Earns Its Place
Vibe coding isn't an engineering failure mode to ban. It's a useful way to explore interactions, test product language, and discover whether an idea deserves implementation.
A discovery workspace should support quick experiments without implying that every artifact will ship.

The Journal of Object Technology review describes vibe coding as useful for exploration while identifying traceability and architectural drift as problems at larger scale. The practical response is to define what the experiment may touch and what must happen before reuse.
Match the work to its promotion gate
Work types matched to workflow fit and merge gate
| Work type | Vibe coding fit | Required gate before merge |
|---|---|---|
| Throwaway prototype | Strong | Delete or rebuild before any production reuse |
| UI mockup or copy test | Strong | Recorded user validation notes |
| Internal script, reversible change | Good | Automated checks pass and rollback is simple |
| Data persistence or schema change | Weak | Schema spec, migration plan and rollback path |
| Authentication or payments | Weak | Explicit spec with security tests |
| External integration | Weak | Contract tests and a named owner |
| Cross-cutting refactor | Weak | Full spec and regression suite |
For a throwaway experiment, merge means an isolated experiment repository, not the production branch. For a UI test, validation notes establish whether the interaction deserves promotion; they don't replace engineering checks if the implementation will ship.
Small-looking changes can cross consequential boundaries. A remember-me checkbox changes session behavior, a saved preference introduces persistence, and a payment button can create duplicate-charge risks.
Promote the learning, not automatically the code
Before production reuse, confirm that users validated the intended interaction. Inspect persistence and authentication, settle external contracts, and assign an on-call owner who can diagnose failure and recover the system.
Keep experimental environments separate from production credentials and customer data. DevArmor's guidance to add security guardrails to vibe coding is a useful companion when setting permissions and checks around agent-driven experiments.
This video offers another perspective on the workflow.
Say a designer explores an onboarding flow with synthetic accounts. Keep the successful interaction and validation notes, but don't automatically keep the generated session handling, database model, or access rules.
An internal script needs the same judgement. A script that formats local fixtures is reversible; one that bulk-updates customer accounts isn't low-risk merely because only employees run it.
The right boundary is consequence and reversibility, not whether the tool is internal or the feature looks simple. Preserve the freedom to experiment, but make production promotion an explicit engineering decision.
Combining Both Workflows and Choosing a Default
Default to spec-driven development for production dependencies, and use vibe coding for bounded discovery with a mandatory promotion step before production merge. That gives engineers room to learn without asking maintainers to inherit an experiment by accident.
Keep discovery context through production
During discovery, retain conversational sessions and record decisions as they change. Distinguish an option the team tried from a behavior it accepted, and preserve the reason it rejected alternatives.
During promotion, extract the decisions, contracts, edge cases, and acceptance tests that survived discovery. Don't turn the entire chat transcript into a specification. Remove abandoned directions, resolve contradictory instructions, and ask the accountable people to approve the resulting contract.
During production, keep that contract current and connect changes to the criteria they satisfy. When behavior changes, update the requirement and its evidence in the same review rather than leaving maintainers to reconcile conflicting artifacts later.
The operating model needs a visible transition, not a vague promise to document things eventually.

A team might build a landing-page prototype during a meeting, then specify the accepted behavior before connecting it to checkout. The visual exploration remains useful, while the payment boundary receives deliberate review.
Stoa's AI listens to meeting conversations and automatically extracts decisions, drafts specs, generates user stories, and flags open questions. That helps preserve the context needed for promotion, but the team still needs to approve the requirements and completion evidence.
SpecStory for Teams stores, shares, and versions prompts alongside code. SpecStory wraps existing AI tools and saves conversations automatically rather than replacing the tools engineers already use.
Run a bounded adoption test
Don't introduce a heavyweight process across every repository at once. Apply the workflow to comparable changes and inspect whether reviewers spend less time resolving ambiguity.
-
Classify recent shipped features. Choose a small sample and label each by work type, production consequence, and reversibility. Identify where an apparent prototype became a maintained dependency.
-
Measure median time to accepted feature and rework rate for those changes. Include product clarification and reviewer effort, not just the time an engineer spent prompting.
-
Adopt the compact spec template. Use the same fields for the next production change, but leave out sections that don't apply rather than filling them with boilerplate.
-
Run the spec gate before merge and record requirement coverage. Have a reviewer inspect the evidence links and challenge whether they demonstrate the intended behavior.
-
Schedule a follow-up review. Compare escaped defects, review iterations, and corrective work with similar changes. Ask whether the process prevented misunderstandings or merely moved typing into a document.
If planning effort rises without clearer reviews or less rework, improve the acceptance criteria and change boundaries before adding more documentation. If experiments keep reaching production informally, strengthen promotion ownership.
The test isn't whether the first draft appeared quickly. It's whether the team reached accepted behavior with less total review and corrective work.
SpecStory, Inc. offers Stoa to capture meeting decisions, draft specifications, and flag open questions, alongside tools that preserve AI coding conversations. Visit SpecStory, Inc. to bring your next feature kickoff into a shared workspace, then use the resulting context to define a reviewable production spec before implementation.
Newsletter
Get new posts in your inbox
Bring your team together to build better products. Fresh takes on remote collaboration and AI-driven development.
