Transitioning From Vibe Coding to Spec-Driven Development

Saying "write me an app" is easy; shipping it to production is a different matter. Vibe coding delivers great results for small prototypes, but as the codebase grows, architectural drift, context loss, and recurring mistakes creep in — exactly where "what is spec-driven development" starts to matter. This post walks through where vibe coding breaks down, what spec-driven development (SDD) actually is, and when to combine the two.

💡 Pro Tip: Don't think of writing a spec as "extra work" — think of it as the contract behind the instruction you give the agent. The clearer the spec, the less code you'll have to review.

Table of Contents

• Why vibe coding breaks down at scale
• What spec-driven development actually is
• The spec → plan → task → code loop
• The cost of writing a spec for small tasks — when it's not needed
• Setting up the SDD flow with CLAUDE.md / rule files
• Keeping the spec alive: when the code changes, the spec must too
• The hybrid model — vibe for exploration, spec for delivery
• FAQ
• What is spec-driven development?
• What's the difference between vibe coding and spec-driven development?
• Which projects should use spec-driven development?
• Does writing a spec slow down vibe coding?
• Where should I keep the spec file?
• Update (September 2026)
• Conclusion
• Sources

Why vibe coding breaks down at scale

The term itself was coined in February 2025 by Andrej Karpathy, an OpenAI co-founder and former Tesla AI lead. Karpathy described the practice of talking to AI like a conversation and leaving the rest to the model; it quickly spread as a way of working "without fully understanding the code, trusting results and follow-up prompts."

GitHub's Spec Kit launch post describes the breaking point clearly: "Sometimes the code doesn't compile. Sometimes it solves part of the problem but misses the actual intent. The stack or architecture may not be what you'd choose." According to the post, the problem isn't the agent's coding ability but our approach: "We treat coding agents like search engines when we should be treating them more like literal-minded pair programmers."

That's not a problem for fast prototyping. In GitHub's own words, "vibe-coding" "can be great for quick prototypes, but less reliable when building serious, mission-critical applications or working with existing codebases." As the codebase grows and your instructions to the agent get vaguer, each new prompt forgets the previous one's assumptions — architectural consistency falls apart.

An early warning from developer Simon Willison, cited in Wikipedia's "vibe coding" entry, points to the same thing: "Vibe coding your way to a production codebase is clearly risky. Most of the work we do as software engineers involves evolving existing systems, where the quality and understandability of the underlying code is crucial." This sums up why vibe coding behaves differently for "writing something new" versus "growing an existing system" — and the second scenario is exactly where spec-driven development delivers its real value.

What spec-driven development actually is

In announcing Spec Kit, GitHub redefines specifications: "Not as static documents, but as living, executable artifacts that evolve with the project." Specs become the shared source of truth: "When something doesn't make sense, you go back to the spec; when a project grows complex, you refine it; when tasks feel too large, you break them down."

It's misleading to view spec-driven development as "the opposite of vibe coding" — it's more like its disciplined form. Under the definition Merriam-Webster gave when it listed the term as a "slang & trending" expression in March 2025, in vibe coding "the developer doesn't need to understand how or why the code works, and usually has to accept that a certain number of bugs and glitches will exist." SDD aims to remove exactly that acceptance: putting what's being built, why, and the acceptance criteria in writing before the code is written.

Thoughtworks' November 2025 Technology Radar (Vol. 33) frames it as follows: "Spec-driven development is an emerging approach to AI-assisted coding workflows... it generally refers to workflows that begin with a structured functional specification, then proceed through multiple steps to break it down into smaller pieces, solutions and tasks." The same report compares three different interpretations; the phase names in the Spec Kit row come from GitHub's own launch post:

All three share the same basic idea — the specification as an artifact that exists before and apart from the code — but they answer "how strict" differently. Spec Kit's "constitution" concept stands out: it keeps the project's never-to-be-violated principles (e.g. "every API endpoint must be tested") in a separate file, referenced at every plan and task step.

The spec → plan → task → code loop

GitHub's Spec Kit follows a process with four clear checkpoints: "It works in four phases with clear checkpoints... you don't move to the next one until the current task is fully validated." The sequence:

1. Specify — you describe your high-level goal to the agent in natural language; the agent turns it into a structured specification.
2. Plan — the specification turns into a technical plan (architectural decisions, data model, interface boundaries).
3. Tasks — the plan is broken down into small, verifiable tasks.
4. Implement — the agent implements the tasks one by one; you review at every step.

In practice, this loop's biggest difference is in how review works. In GitHub's words: "Instead of reviewing thousand-line code dumps, you — the developer — review focused changes that solve specific problems." The spec acts as a filter, breaking the agent's diff into small, traceable pieces.

When writing your own spec file, a minimal skeleton like the one below works well — the goal is to answer the "what," "why," and "when is it done" questions up front for the agent:

1# Spec: User notification preferences
2 
3## Problem
4 
5Users can't choose which type of notification they receive.
6 
7## Acceptance criteria
8 
9- User can choose between email/push/none
10- Preference change is saved instantly
11- Default: all notifications on
12 
13## Out of scope
14 
15- Notification frequency setting (next iteration)

The cost of writing a spec for small tasks — when it's not needed

Writing a spec isn't free. Thoughtworks' November 2025 Technology Radar deliberately placed SDD in a cautious ring — "Assess" (try it, but don't recommend broad adoption yet) — and noted: "We find this space fascinating, but the workflows are still complex and opinionated. These tools behave very differently depending on task size and type; some produce long spec files that are hard to review."

That doesn't mean "write a spec for everything." I use this distinction: a spec for a single-file bug fix, a button color change, or an isolated helper function costs more than the problem it solves — there, moving straight ahead with "vibe" is more rational. A spec's value rises as the work grows, touches multiple files/services, and "acceptance criteria" get less clear.

In practice, tasks that don't need a spec share a trait: scope reviewable in one sitting, cheap to revert, no architectural decision. Tasks that need one, on the other hand, touch multiple layers (API + DB + UI), have a disputed definition of "done," or are an area where the agent proceeded on a wrong assumption before.

Roughly, decide with this table:

Setting up the SDD flow with CLAUDE.md / rule files

What spec-driven tools have in common is giving the agent persistent context, not one-off context. GitHub built Spec Kit to work with multiple agents, including Claude Code, GitHub Copilot, and Gemini CLI — so spec files are the project's shared contract, not one tool's.

Claude Code already has this mechanism: the CLAUDE.md file at the project root loads automatically every session and tells the agent the project's rules, directory structure, and "don't do this" list. The practical way to combine SDD with CLAUDE.md is to keep them at different layers: CLAUDE.md carries permanent rules (tech stack, deploy flow, prohibitions), while the spec file carries the current task's acceptance criteria.

1# CLAUDE.md (project-wide rule file — permanent)
2 
3- Tech stack: Next.js + Prisma, tests in Vitest
4- New features start with spec.md first, then plan+tasks
5- Spec is mandatory for critical flows (payment/auth); optional for small fixes

This separation keeps the agent from re-asking "how does this project work" every time; the spec file, in turn, answers "when is this task done."

Let me show a short example of how a spec file can be used as a checkpoint during code review — you can keep the acceptance criteria as comment lines in bash and check them off one by one while reviewing:

1# review-checklist.sh — check spec.md's acceptance criteria against the PR
2# [ ] Can the user choose between email/push/none?
3# [ ] Is the preference change saved instantly?
4# [ ] Is the default all notifications on?
5# The PR isn't approved until every line has a match in the agent's diff

Keeping the spec alive: when the code changes, the spec must too

One of the most critical sentences in GitHub's Spec Kit post is this: specs are "not static documents, but living, executable artifacts that evolve with the project." That's the exact opposite of the trap traditional PRDs fall into — shelved once approved, gradually drifting away from the code.

In practice this means: "When something doesn't make sense, you go back to the spec; when a project grows complex, you refine it; when tasks feel too large, you break them down." The spec isn't a one-way input — it's part of a feedback loop. When the agent writes code that conflicts with an assumption, fix the spec first, then regenerate the code — don't patch the code by hand and leave the spec outdated.

The simplest way to enforce this discipline: keep the spec file in the same pull request as the code. If the code changes without the spec changing, that PR has an inconsistency — and that's the first place to look during review.

The hybrid model — vibe for exploration, spec for delivery

GitHub's own framing is a guide here too: "This 'vibe-coding' approach can be great for quick prototypes, but less reliable when building serious, mission-critical applications or working with existing codebases." That single sentence really describes the hybrid model — which mode to use at which stage.

In practice, a three-stage flow works well:

• Exploration (vibe): To quickly answer questions like "what does this look like, how does this API behave," prompt the agent directly in natural language, run the code, throw it away, try again. The goal is to learn, not to produce.
• Decision (spec): Write the approach that becomes clear during exploration into spec.md — acceptance criteria, out-of-scope, architectural constraints.
• Delivery (implement): Ask the agent for small, reviewable diffs based on the spec; verify every diff against the spec.

As long as the cost of moving between these three stages stays low, the hybrid model frees you from the "all vibe or all spec" dilemma.

Take a concrete example: adding a "favorite products" feature to an existing e-commerce app. In exploration, ask the agent "how should the UI react when a user favorites a product" and have it produce a few quick prototypes — you're checking which feels better, not writing production code. In decision, write the approach that emerged ("the favorite button does an optimistic update, rolling back on backend error") into the spec. In delivery, ask the agent, based on that spec, for the data model, then the API endpoint, then the UI component as separate diffs, checking each against the spec's acceptance criteria. None of the exploration code gets copied into delivery — only the decision learned carries over.

FAQ

What is spec-driven development?

Spec-driven development is an emerging approach in AI-assisted coding workflows; it typically starts with a structured functional specification and continues through a multi-step process breaking it into smaller pieces, solutions, and tasks (Thoughtworks Technology Radar Vol. 33 definition). In GitHub's Spec Kit, this maps to four phases: Specify → Plan → Tasks → Implement.

What's the difference between vibe coding and spec-driven development?

In vibe coding, the developer describes the goal in natural language and trusts the results without deeply understanding how the code works; per Merriam-Webster, they "usually have to accept that a certain number of bugs and glitches will exist." Spec-driven development instead puts acceptance criteria, scope, and architectural constraints in writing before the code exists; in GitHub's words, review happens through "focused changes," not "thousand-line code dumps."

Which projects should use spec-driven development?

Per Thoughtworks, tools "behave very differently depending on task size and type." A spec is valuable for work touching multiple layers, integrating into an existing codebase, or with a disputed acceptance criterion — GitHub's "serious, mission-critical applications" fall here.

Does writing a spec slow down vibe coding?

Short-term, yes — it adds a thinking step before coding. But Thoughtworks' cautious note shows this is a trade-off: "workflows are still complex and opinionated." For small, single-file tasks the cost doesn't pay off — using a spec only where scope is large and rollback expensive raises overall speed instead of lowering it.

Where should I keep the spec file?

In the same repo as the code, alongside the relevant pull request — so any spec/code inconsistency is spotted immediately during review. Project-wide rule files like CLAUDE.md carry permanent rules; the spec file carries the current task's acceptance criteria.

Update (September 2026)

The body of this article was written with information valid as of November 18, 2025. Since then, both the risks of vibe coding and the scope of spec-driven tools have expanded considerably.

The evidence got heavier. In December 2025, CodeRabbit's analysis of 470 open-source GitHub pull requests found code co-written with generative AI had roughly 1.7x more "major" issues than human-written code; misconfigurations were 75% more frequent, security vulnerabilities 2.74x higher. Around the same time, a vulnerability found by researcher Etizaz Mohsin in a vibe coding platform called Orchids was demonstrated to BBC News in February 2026.

Vibe coding fully entered the mainstream. In January 2026, Linus Torvalds "vibe-coded" a visualization tool for a hobby sound-effect generator using Google Antigravity, attributing it to his limited Python knowledge in the project's README.

Spec Kit expanded from a single flow to multiple entry points. As of today (September 23, 2026), its README no longer defines just "build with a spec" but also independent entry points like "fix a bug" and "assess an idea." Its star count reached 139k on the same date; Amazon Kiro's public feedback repository, compared in the Thoughtworks Radar in November 2025, stands at 4.3k stars — that repository is not the product's own source code repository.

Together, these three developments paint a clear picture: vibe coding's scaling problems became more concrete with data, while spec-driven tools expanded beyond just "write a new feature" (bug fixes, idea assessment), bringing the disciplined workflow to a wider range of work.

Conclusion

Vibe coding and spec-driven development aren't a competition — they're two stages of the same workflow. Trusting vibe for speed during exploration, then switching to a spec for delivery, prevents architectural drift without giving up the agent's power. In Claude Code, the natural way to set this up is keeping permanent rules in CLAUDE.md and the current task's acceptance criteria in a separate spec file.

Next, before letting the agent write a large feature in one shot, try Claude Code Plan Mode; for parallel agents, see Multi-Agent Teams. Pitfalls of moving from vibe coding to production are covered in the Guide to Moving a Vibe-Coded MVP to Production and the Vibe Coding Security Checklist. For testing the agent's code in a spec-driven flow, see AI-Assisted Unit Test Generation.

Sources

• Spec-driven development with AI: Get started with a new open source toolkit — GitHub's official Spec Kit launch post; the four-phase Specify/Plan/Tasks/Implement process and the "living, executable artifact" definition.
• Spec-driven development — Thoughtworks Technology Radar Vol. 33 — November 2025; the primary source placing SDD in the "Assess" ring, with the Kiro/Spec Kit/Tessl comparison.
• Vibe coding — Wikipedia — Timeline including Karpathy's February 2025 origin, CodeRabbit's December 2025 analysis, and the January 2026 Torvalds example.
• 'Vibe coding' named word of the year by Collins Dictionary — BBC News, November 6, 2025; confirms Karpathy coined the term in February 2025, and covers Collins' Word of the Year announcement.
• github/spec-kit — GitHub repository — Spec Kit's current (September 2026) README, evidence of the "build with a spec, fix a bug, or assess an idea" expansion.
• kirodotdev/Kiro — GitHub repository — Amazon Kiro's public feedback repository; 4.3k stars as of September 23, 2026 (GitHub API: 4,330), source of the Kiro figure in the "Update" section.
• Spec Kit — GitHub stars badge (shields.io) — Live star count as of September 23, 2026 (139k), source of the "Update" section figure.