MVP in 2 Weeks
When vibe-coded speed beats spec overhead.
TL;DR
- Spec-driven workflows shine when agents implement features from structured PRDs—but pre-seed teams often ship faster with vibe-coded MVPs first.
- Contrast: vibe coding optimizes for learning speed; spec-driven optimizes for change control and multi-engineer alignment.
- Over-specifying before product-market signal burns runway—spec the workflow you validated, not the roadmap fantasy.
- Tools like Cursor, Claude Code, and internal agents consume specs best when APIs, acceptance criteria, and eval hooks are explicit.
- Graduate to spec-driven when second engineer joins or when compliance demands audit trails.
What It Is
Spec-driven development (SDD) means features start as structured specs—user stories, acceptance tests, API contracts, design constraints—that coding agents (and humans) execute against. Changes flow spec → implementation → verification, not ad-hoc prompt sessions in isolation.
It resembles rigorous PRD culture, but specs are written for machines: typed interfaces, Gherkin scenarios, OpenAPI files agents can parse. The goal is reproducible builds when more than one agent or engineer touches the repo. Specs should be boring, testable, and small—creativity belongs in discovery, not in ambiguous requirements.
SDD is not waterfall cosplay—it can iterate daily if specs are small batches tied to validated learning. The discipline is writing specs small enough that agents finish in hours, not weeks—then merging only when acceptance tests and metric checks pass. If the spec takes longer to write than the feature, your scope is still too big.
Why It Matters Now
Coding agents changed the bottleneck from typing speed to ambiguity. When Cursor-class tools generate hundreds of lines per hour, missing acceptance criteria produce merge-ready garbage. SDD emerges as founders hit the wall where vibe-coded MVPs collapse under second-feature complexity. The telltale symptom is recurring “it worked yesterday” bugs after agent refactors without documented acceptance criteria.
Pre-seed teams still benefit from two-week vibe-to-MVP sprints to find signal—SDD becomes valuable once a workflow proves retention and you hire engineer #2 or face SOC2 questions. The transition point is organizational: when more than one person or agent must implement without telepathy, specs pay rent.
Pair SDD with eval harnesses so spec acceptance includes agent behavior, not only unit tests.
Comparison at a Glance
| Style | Best stage | Strength | Weakness |
|---|---|---|---|
| Vibe coding | Pre-seed / idea | Fastest learning | Undocumented debt |
| Light specs (one-pagers) | Seed MVP | Balance speed/clarity | Still informal |
| Full SDD | Post-PMF / compliance | Multi-agent + multi-eng sync | Overhead if premature |
| Ticket-only agile | Any | Familiar process | Agents ignore Jira silently |
Step-by-Step Workflow
Adopt SDD incrementally:
- After first retained cohort, write spec templates: problem, acceptance criteria, non-goals, telemetry.
- Generate implementation plans from specs via agents—human approves before code.
- Bind CI to spec tests—acceptance scenarios run on every PR.
- Version specs in git alongside code; link PRs to spec diffs.
- Retire specs when features die—stale specs confuse agents worse than none.
Align specs with PLG instrumentation so acceptance includes metric movement, not only green tests. A spec that passes CI but does not move activation is still a failed spec.
Common Pitfalls
- SDD before validation: documenting features users never requested—classic GenAI pilot trap.
- Specs too vague for machines: “make it intuitive” guarantees agent hallucination.
- Spec bureaucracy: committees writing 40-page PRDs while competitors ship ugly MVPs—specs should fit in one sprint, not one quarter.
Best Practices
- One spec per shippable slice—mergeable in days, not quarters.
- Include eval scenarios for AI features—expected tool calls, failure copy, latency budgets.
- Keep a vibe-coding sandbox for spikes; promote to spec only when repeating work or when a second engineer needs the same context.
Is This the Future?
Spec-driven development is overkill for pre-seed founders still hunting one painful workflow—it is essential when agents and engineers share a repo at scale. The mistake is copying enterprise process without enterprise constraints.
Vibe code to learn; spec to scale. If you cannot name the workflow you validated last month, specs will not save you. Write the spec for the workflow that already retained users—not the platform you hope to build next year.
Your first spec should be one page and one feature; length is not maturity. Ship it.
Frequently Asked Questions
Is spec-driven development anti-AI?
Opposite—agents need clarity. SDD is how you aim agents without micromanaging every line.
What belongs in a machine-readable spec?
User outcome, acceptance tests, API shapes, error states, analytics events, non-goals, and security notes for PII. Add explicit latency and cost budgets when the feature uses LLM calls.
When is SDD overkill?
Solo founder pre-revenue testing ideas—use fast MVP sprints until retention proves a workflow. SDD starts when a second builder touches the same agent workflow twice in one week.
Do investors care about SDD?
They care you can scale engineering without chaos. SDD is one signal—not a substitute for metrics. Show one example spec-to-ship cycle with eval results in diligence, not a process diagram.
How does SDD interact with multi-agent builds?
Specs become agent task graphs—see framework comparison for orchestration binding.