From Vibe Coding to Spec-Driven Development

"Vibe Coding" is a term that spread widely in 2025, describing a development style where you write little to no spec and instead generate code through back-and-forth dialogue with AI.

You watch the behavior, layer on more prompts, and if it works, it's good enough. Vibe Coding is especially powerful for prototyping and short-lived tools. On the other hand, in team development and long-term operation, the spec and the reasoning behind decisions tend not to survive — and that becomes the problem.

What is Vibe Coding?

This article covers what "Vibe Coding" and "Spec-Driven Development (SDD)" each mean, why Vibe Coding became popular and where it runs into limits, the basic SDD workflow and representative tools such as GitHub Spec Kit and Kiro, and practical tips teams can start using today.

It's written for early-to-mid-level engineers who use coding agents like ChatGPT, Claude Code, or Cursor on a daily basis — particularly those who have already had AI write code for a personal project.

Where Vibe Coding shines

Vibe Coding works well in situations like these:

• Personal prototyping or idea validation
• Throwaway scripts or internal tools
• Phases where you just want to see something working, fast
• Getting a quick "feel" for an unfamiliar technology

What these have in common: the output is short-lived, and it's enough for one person — you — to understand it. Under that condition, writing a detailed spec often doesn't pay for itself.

Nobody writes a requirements document for an app they'll throw away 24 hours after a hackathon, and a ten-line script that just fires a Slack notification doesn't need a design review.

It's also easy to overlook that Vibe Coding has real exploratory value: it's the fastest way to learn things you can only learn by building. In many cases you reach what you "actually wanted" faster by touching something rough that works than by working out the spec in your head — and that learning speed is Vibe Coding's real weapon.

What is Spec-Driven Development (SDD)?

Spec-Driven Development grew out of that reflection. The idea is simple: instead of treating code as the first thing you generate, you put the spec at the center of development as the first-class artifact, and treat code as a derivative that's generated from that spec.

The key point is that a "spec" in SDD isn't just something to read. In the AI era, a spec functions less like a fixed document for humans to read later, and more like an "evaluation function" that mechanically checks whether the AI's output is correct.

The clearer the spec, the less the AI agent wanders, and the more reviewers can judge purely against "does it match the spec."

The relationship between Vibe Coding and SDD

The two aren't opposing philosophies so much as a matter of which one you reach for at each phase of development.

Table 1. Vibe Coding vs. Spec-Driven Development.

You use Vibe Coding early on to discover "what you want to build," then once direction is set, you translate it into a spec and move into SDD. That back-and-forth is the realistic development style of the AI era.

How to measure the effect of adopting SDD

Here we organize practical metrics for measuring SDD's effect: quantitative metrics that look at rework and review cost, and qualitative metrics that track how team conversation and onboarding change.

Quantitative metrics: rework and review cost

The clearest signal is a drop in rework. Concretely, compare these numbers before and after adoption:

• Number of fix commits per PR (additional commits driven by review feedback)
• Number of PRs sent back or rebuilt due to "misalignment on the spec"
• Lead time from review start to merge
• Number of spec bugs found after merge (implementation is correct, but doesn't match the requirement)

If SDD is working, misalignment on the spec gets caught earlier — during Clarify or spec review, before implementation — so these numbers should trend down. One caveat: right after adoption, overall lead time can temporarily increase because the cost of writing the spec gets added on top.

For the first month or two, it's more realistic to focus narrowly on "rework caused by the spec." Also, tying these metrics to individual performance reviews tends to invite gaming the numbers — it's strongly recommended to treat them purely as material for improving the team's process.

Qualitative metrics: changes in team conversation and onboarding

A change that doesn't show up in numbers but is unmistakable once you see it: the quality of conversation inside the team.

Before SDD, review comments tend to center on implementation details — "this variable name," "this needs a null check." After adoption, questions like these move into the spec review stage:

• What do we do about this requirement's edge case?
• This feature we put out of scope — are we sure it's fine for the next phase?

The discussion itself moving upstream is a sign that SDD is working.

Another easy-to-spot change is onboarding for new members. Because the history of specs, design, and tasks lives in the repository, a new hire can trace "why does this feature work this way" without having to ask anyone.

Vibe Coding vs. SDD: the standard SDD workflow

GitHub Spec Kit, a representative tool, offers a four-stage workflow:

1. Specify — describe in natural language "what" you're building and "for whom," without touching on implementation.
2. Plan — spell out the tech stack, architecture, and constraints you'll use.
3. Tasks — break the work down into implementable units.
4. Implement — an AI coding agent (Claude Code, GitHub Copilot, Cursor, etc.) executes the tasks.

How to use and set up GitHub Spec Kit

Spec Kit is an open-source CLI tool that integrates with 29 different AI coding tools, including Claude Code, GitHub Copilot, Gemini CLI, and Cursor.

Here's a real example of code you'd actually run in the CLI:

Once initialized, slash commands like /specify, /plan, /tasks, and /implement get added on the AI agent side, letting you move through spec → design → tasks → implementation in conversation.

With this flow, the AI agent writes code while holding onto the spec and the plan as its "anchor," so implementation drifts less from the spec.

Early case studies from GitHub and AWS report that on non-trivial tasks, the AI agent's one-shot success rate improved by 3–10x.

IDE-integrated: the AWS Kiro example

Kiro, provided by AWS, is an IDE built around SDD from the ground up. If combining CLI tools isn't your preference, it's an option that lets you experience the spec → design → tasks → implementation flow as an IDE UI.

Spec Kit's main features are:

• Specs — you describe requirements in chat, and Kiro automatically breaks them into three files: requirements.md, design.md, and tasks.md. You review and revise these three files before moving to implementation.
• Sequential task execution — tasks broken down in tasks.md get executed by the AI one at a time, with you checking the diff each time. Rather than throwing one big change at it, like Vibe Coding, changes are chunked into reviewable pieces.
• Steering — placing Markdown files under .kiro/steering/ lets the AI constantly reference project-specific rules. There are three load modes — always (loaded every time), fileMatch (only when editing matching files), and manual (explicitly invoked with #filename) — and it's recommended to keep it to around 3–5 files per task so context doesn't get crowded out. Personal settings can also live globally at ~/.kiro/steering.
• Agent Hooks — triggered by events like file saves or commits, these can automatically run actions such as code scans or documentation updates — also useful as a safety net against missed spec/design updates.
• MCP integration — external tools and data sources can be connected via MCP, letting you wire internal systems into the spec-driven workflow.
• Model selection — you can switch between multiple frontier models, such as Claude Opus and Sonnet, depending on the nature of the task.

Where Spec Kit is CLI-based and bolts onto your existing editor and agent, Kiro's biggest difference is that spec/design/task management is itself built into the IDE. If you want to force a unified workflow across the team, Kiro; if you want to keep the feel of your existing Claude Code or Cursor setup, Spec Kit — that's the practical way to choose.

What makes a good spec: writing specs AI can understand

Once the workflow is running, the next question you hit is "what exactly should I write in the spec, and how?" Since SDD's success or failure comes down almost entirely to the quality of the spec, here are three practical principles: write intent, not implementation; replace vague words with verifiable conditions; and explicitly state what's out of scope.

Write intent, not implementation

A common beginner mistake is writing implementation steps into the spec. For example:

"Add an is_verified column to the users table, and only allow login when the flag is true."

That's an implementation instruction, not a spec. Written this way, the AI loses room to consider better design choices, and every time you change the implementation later you're forced to rewrite the spec too.

What you should write instead is intent: "A user whose email ownership hasn't been verified cannot access the service's core features. Even before verification is complete, resending the verification email must still be possible." The principle is to write only "what must hold true," and leave "how it's satisfied" to the Plan stage and beyond.

Replace vague words with verifiable conditions

A spec in SDD is an evaluation function. To function as one, every sentence in the spec needs to be in a form where a third party can judge whether it was satisfied.

Watch for vague language — phrases like "displays quickly," "an easy-to-use UI," or "handles large amounts of data" are all expressions where the AI can claim it "satisfied" the spec no matter what it actually built. Replace each with a form that carries a number, a condition, a boundary: "the list view's initial render completes within 1 second," "the main operation completes in 3 clicks or fewer," "processes a 100,000-row CSV within 30 seconds."

You can't quantify everything, but simply building the habit of re-reading what you wrote and asking "is there room for me and the AI to disagree on whether this sentence was satisfied?" changes the quality of your specs.

Explicitly state what's out of scope

A surprisingly effective move is writing down what you're not going to do. AI agents tend to add features out of helpfulness. It looks considerate, but a feature nobody asked for means untested spec and unreviewed design decisions are sneaking into the codebase. Just one line in the spec —

"Out of scope: social login, password reset" —

is enough to prevent this kind of scope creep.

An out-of-scope list also has the added effect of aligning the team's understanding. Once "we're not doing this feature" is written down explicitly, rework after implementation can be skipped entirely.

Pitfalls you hit once you put it into practice

Once you actually start running the SDD workflow on a personal project or within a team, you run into small snags that don't show up in the documentation. Here are the three most frequent, in Q&A form.

Conclusion and next steps

Vibe Coding is a weapon for exploration and prototyping; Spec-Driven Development is a weapon for real implementation, team development, and production operation — each has its own strength. The axis AI-era engineers need to hold onto isn't "does the AI write it or does a human write it," but "who fixes the spec, and when."

Start small: try running through GitHub Spec Kit's /specify to /implement once on a small personal task. Getting a feel for having the AI write code once the spec has taken shape is the shortcut to the next step.

Coding practices update frequently, so check the latest official documentation below as well.