DEV Community

Rocio Jacob
Rocio Jacob

Posted on

Vibe coding got me 80% there. Spec-Driven Development got me the other 20%.

#ai #productivity #softwareengineering

I like vibe coding. I'm not here to shame anyone out of it. Some of the best things I've shipped started as a half-formed idea typed into a chat box at 11pm.

But if you've done this for more than a weekend, you know the shape of the problem. The first prompt is magic. The fifth one is negotiation. By the fifteenth you're re-explaining a decision you already made twice, the agent has quietly renamed your data model, and you're one "fix the header" away from deleting the folder and starting over.

The bottleneck was never the code. The agent writes code faster than I ever will. The bottleneck is clarity — and clarity is the one thing I kept keeping in my head instead of in the repo.

That's the gap Spec-Driven Development fills, and Spec Kit is the toolkit that makes it practical.

What is Spec-Driven Development?

SDD is a simple inversion: the specification is the artifact you maintain, and the code is what gets generated from it.

Not "write a PRD, then throw it away once real work starts." The spec lives in the repo, next to the code, in version control, and it's the thing you edit when you want the software to change.

A real spec answers three things:

  • What the system does — entities, flows, screens, rules
  • How it must behave under constraints — auth, performance, compatibility, accessibility
  • Why the key decisions were made

And it deliberately does not answer "which framework." That comes later, on purpose.

The reason this matters more now than it did in 2015: your agent doesn't have your context. It has whatever you gave it in the last 4,000 tokens. A spec is context that survives a new chat window, a new model, and a colleague who joins on Tuesday.

So what is Spec Kit?

Spec Kit is GitHub's open-source toolkit for doing this. It launched in September 2025 as an experiment and it did not stay an experiment: 130K+ stars, 270+ contributors, 38 agent integrations, and a whole ecosystem of community extensions and presets.

Install and scaffold:

uv tool install specify-cli
specify init my-project --integration copilot
Enter fullscreen mode Exit fullscreen mode

That drops a .specify/ folder plus slash commands into your agent (Copilot, Claude Code, Codex, Gemini, Cursor, Kiro, Zed — most of them). Then the workflow runs in chat:

/speckit.constitution → /speckit.specify → /speckit.clarify → /speckit.checklist
→ /speckit.plan → /speckit.tasks → /speckit.analyze → /speckit.implement
Enter fullscreen mode Exit fullscreen mode

Every step produces a Markdown file that feeds the next one. Nothing is a black box. No proprietary editor. You can open any of it and type over it with your own hands, which you absolutely should.

Two pieces deserve special attention:

The constitution (.specify/memory/constitution.md) holds your non-negotiables. "Static-first delivery." "No new dependencies without justification." "Every migration ships with a rollback." Every later phase is checked against it. This is the single highest-leverage file in the whole setup, and most people leave it as boilerplate.

The gates — /speckit.clarify, /speckit.checklist, /speckit.analyze — are what separate this from prettier prompting. clarify hunts for ambiguity before you plan. checklist grades the requirements themselves. analyze cross-checks spec vs. plan vs. tasks before a single file gets written. For a quick prototype you can skip them. For anything you'll have to maintain, don't.

Why would I use it?

Four honest reasons.

1. It moves the argument earlier. Fixing a misunderstanding in a Markdown file costs a minute. Fixing it after 40 generated files costs an afternoon and your patience.

2. It makes the work reviewable by people who don't read code. This is the one that changed things for me. A spec is something you can send to a stakeholder, a PM, or a boss, and get real feedback on. Try doing that with a chat transcript.

3. Model churn stops being a threat. If the agent produced something mediocre, you don't lose the thinking. Delete the source, switch models, re-run /speckit.implement. Your spec is the durable asset; the implementation is disposable. That's a much better position to be in every time a new model drops.

4. It scales past one person. Chat context doesn't merge. Markdown in a git branch does.

How will my projects actually improve?

Concretely, from the pattern I keep seeing:

  • Fewer "start over from scratch" cycles. The rework loop shrinks because the misunderstanding gets caught upstream.
  • Edge cases you wouldn't have thought of. The spec templates force sections for acceptance scenarios and edge cases. The agent fills them, you correct them. Free QA thinking.
  • Onboarding stops being a conversation. "How does this work?" → read specs/001-*/spec.md.
  • Better decisions, because you had to write them down. Half the value shows up before you run anything. Writing the spec is where you notice that you never decided how episodes are ordered, or what happens when the list is empty.
  • Structured additive change. New feature = new spec folder = new branch. Your third feature doesn't quietly rewrite your first.

The honest trade: it's slower on day one. For a landing page you'll ship this afternoon, this is ceremony. For anything with more than one screen, more than one contributor, or a lifespan longer than a demo, it pays for itself fast.

Are there real-world examples?

Yes, and I want to give you both halves of the picture.

The supportive side: GitHub dogfoods Spec Kit on Spec Kit itself for substantial features. AWS built the same philosophy directly into Kiro and publishes customer cases where multi-day features shipped in a fraction of the human time when authored spec-first. There's a growing academic literature framing specs as the version-controlled contract between humans and agents, and community walkthroughs now cover brownfield adoption in .NET, Java, and Go/React codebases.

The skeptical side, which you should read too: Thoughtworks put SDD in the Assess ring of their Technology Radar, not Adopt, and they push back hard on the idea that specs replace code as the source of truth. There's a fair critique circulating that SDD is contract-design and waterfall with better branding — and the sharpest version of that critique is also the best argument for it: the value is the thinking you do while writing the spec, not the tooling around it. Vendor-reported multipliers should be treated as directional, not proven.

My read: the durable, less-disputable finding is that the human's time moves from typing implementation to specifying and reviewing. Whether that's a 3x or a 1.2x depends entirely on you.

How do I apply it to a Product Engineering pipeline?

This is where it gets interesting, because the workflow maps almost one-to-one onto roles you already have.

Phase Command Who owns it
Guardrails /speckit.constitution Tech lead + product, once per repo
What & why /speckit.specify Product / PM
Kill ambiguity /speckit.clarify + /speckit.checklist Product + eng together
How /speckit.plan Engineering
Breakdown /speckit.tasks Engineering
Consistency audit /speckit.analyze Whoever reviews the PR
Build /speckit.implement The agent, supervised

A few things that make this work in a real org rather than a demo:

  • The spec review is the new design review. Put it in the PR. That's your approval gate, and it's a much better artifact to argue over than a diff.
  • One feature, one branch, one spec folder. Spec Kit picks up the active feature from your git branch, so this falls out naturally.
  • Brownfield is supported and it's the normal case. Don't try to retro-spec your whole system. Initialize in place with specify init --here --force --integration <key> on a clean review branch, write a constitution from rules that are already true in your repo, then pick one bounded change — a CSV export, one endpoint — and run the loop on that.
  • Decide up front how specs age. Frozen historical snapshot per feature, or living contract you regenerate from? Both are valid. Choosing neither is how you end up with docs that lie.
  • Wire the constitution into CI eventually. Community extensions already do architecture and compliance gates. That's where this stops being a personal workflow and starts being governance.

Tips to actually get value out of it

  • Write the constitution yourself. Let the agent draft it, then delete two-thirds. Short and true beats long and aspirational. Unrealistic rules become noise the agent learns to ignore.
  • Use different models for different phases. Reasoning-heavy models are good at scaffolding specs and plans; I switch for implementation. Experiment — it's the only way to find out what works for your stack.
  • Never skip /speckit.clarify on real work. Unresolved [NEEDS CLARIFICATION] markers are the agent telling you where it's about to guess.
  • Edit the Markdown with your hands. People freeze up because "the LLM wrote it." It's a text file. If you want the logo centered, add a functional requirement and move on.
  • Don't over-specify. If your spec has become pseudocode, you've written the program twice. Specify behavior and constraints, not implementation.
  • Implement in phases. Core flow first, validate, then the rest. Dumping 60 tasks into one run saturates context and quality falls off a cliff.
  • Keep the spec free of tech choices. It feels unnatural. Do it anyway — it's what lets you regenerate the same product on a different stack later.
  • Feed it real design context. Hook up MCP servers (Figma, your issue tracker) so the plan references your actual design system instead of inventing one.
  • Treat a bad output as a spec bug first. Before you re-prompt, go read what the spec actually said. Nine times out of ten it's ambiguous there.

What should I research before starting?

Set aside an afternoon, not a week:

  1. Your toolchain: uv / uvx for the CLI, and which integration key matches the agent you already use.
  2. The core concept pages in the Spec Kit docs — "What is SDD?" and "Spec Persistence Models." Those two decide how you'll work six months in.
  3. EARS notation for writing requirements that are unambiguous by construction. Cheap to learn, big payoff on spec quality.
  4. The critiques. Read the Thoughtworks position and the "same patterns, new hype" argument before you adopt this. You'll use the tool better if you know where it's weak.
  5. Your own repo's actual conventions — README, ADRs, CI config, contribution guide. That's the raw material for a constitution that's true instead of invented.
  6. The alternatives, so you're choosing rather than defaulting: Kiro, cc-sdd, BMAD, and the Spec Kit preset ecosystem if you want a different process shape entirely.

The one-line version

Vibe coding optimizes for the first version. Spec-Driven Development optimizes for every version after that.

Implementation is cheap now. Clarity isn't. Spec Kit is a way of putting your clarity somewhere it won't evaporate when you close the tab.

Start small: pick one feature you were going to vibe out this week, run it through the loop instead, and compare how it feels on the third change request.

Sources & further reading

Top comments (1)

Collapse
 
ahmetozel profile image
Ahmet Özel •

"The fifth one is negotiation" is a precise description of the failure. What you are actually paying for by prompt fifteen is that every decision you made lives only in a transcript, so the agent has no way to distinguish a deliberate choice from an accident and helpfully renames your data model. The part of SDD that does the work for me is less the spec document and more that decisions become diffable - when the agent changes behaviour, the spec change shows up in review instead of surfacing three weeks later as a bug. The failure mode to watch is the spec going stale while code moves on, at which point you have two sources of truth and the worse one is authoritative. Anything that regenerates from the spec keeps that honest, anything that only reads it once does not.