This question comes up in almost every team that starts writing code with AI agents in earnest: is vibe coding enough, or should you move to spec-driven development? The short answer: the two are not enemies. Vibe coding is the fastest path from idea to demo when the code may be thrown away; spec-driven development (SDD) is how you keep an agent aligned with your intent when the code has to live a long time. This article breaks down how each actually works, shows what a specification looks like in practice, compares both on explicit criteria, and names the alternatives in between. One thing we do not do: claim either approach is universally faster or better. That depends on the cost of failure in your project, not on any article.
What exactly is vibe coding?
Vibe coding is building software by describing the outcome you want to an AI, then accepting its output without reading every line. The term comes from Andrej Karpathy’s post on February 2, 2025: writing software by “fully giving in to the vibes and forgetting the code even exists.” Karpathy framed the practice for throwaway weekend projects, and that detail matters — the original definition deliberately trades line-by-line understanding for idea-to-demo speed.
The mechanism is simple. You write a natural-language prompt, the agent generates code, you run it, then paste error messages back until the result works. The human’s role shifts from author to operator and tester: you no longer know exactly what was written, only the behavior you can see. As long as the code is disposable, that trade is rational. Trouble starts when the same practice is applied to systems that must live long. Code nobody has read is code nobody can answer for when it fails, and the knowledge of why it looks this way does not live in the repository — it lives in a chat history that disappears when the session closes.
What is spec-driven development?
Spec-driven development makes the written specification, not the chat history, the primary artifact and the source of truth. The most visible implementation today is GitHub’s Spec Kit, an open-source toolkit with roughly 140k stars when we captured it on October 1, 2026. According to its official documentation, the core flow is structured: Specify → Plan → Tasks → Implement → Converge. You write a behavioral specification, the agent drafts a technical plan, the plan is broken into a task list, the agent implements those tasks, and a convergence step checks the result against the spec. Each phase produces a Markdown artifact that feeds the next, so the agent works from structured context instead of ad-hoc prompts.
In practice you drive that flow through slash commands in your agent — /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement for the short path, with /speckit.clarify, /speckit.analyze, and /speckit.converge as extra quality gates on the full path. There is also a /speckit.constitution step that sets standing project rules (conventions, constraints, principles the agent must not violate) before any feature is written. Spec Kit works with many coding agents — the documentation lists 38 integrations, including Copilot and Claude Code — and is installed via the specify init CLI. The point is not the tool itself but the specification’s position as a contract: it can be reviewed before any code exists, it lives in git, it can be diffed when it changes, and it can be audited when someone asks why the system behaves this way.
What does a specification look like in practice?
A good specification records intent, acceptance criteria, and constraints — not code. Here is an illustrative example for a password reset feature; it is not a real project, only a demonstration of the artifact’s shape:
# Specification: Password reset
## Intent
A user who forgot their password can reset it without contacting an admin.
## Acceptance criteria
- Requesting a reset link sends an email containing a single-use link that
expires after 30 minutes.
- Used or expired links are rejected with the same message, without leaking
whether the email is registered.
- The new password is at least 12 characters; all other active sessions are
revoked after a successful reset.
## Constraints
- Do not change the existing user table schema.
- Rate limit: at most 3 reset requests per email per hour.Compare that with the equivalent vibe prompt: “build me a secure forgot-password feature.” That one sentence hands every decision — token expiry, session revocation, email enumeration leaks — to the agent’s defaults, and those defaults differ between models and between days. A specification makes those decisions explicit and debatable before a single line of code exists; disagreement surfaces in a document that is cheap to change, not in a diff that is expensive to throw away. It is also an artifact the next team member can read without guessing intent from code.
When does each approach make sense?
The dividing line is not the labels “prototype versus production” but the cost of failure and the lifespan of the code. Four concrete situations:
- A weekend prototype to validate an idea. You want to know whether the idea deserves more time, not to build a foundation. The code gets deleted once the decision is made. Vibe coding wins here — writing a specification for code you will delete is bureaucracy.
- A hackathon demo. The deadline is measured in hours, there are no users after the presentation, and nobody will maintain the code. Vibe coding again; this is exactly where Karpathy’s original framing applies in full.
- A production system with real users and customer data. Every behavior change must be reviewable before release and traceable afterward. SDD makes sense: the specification is the decision record, and the agent works inside boundaries you wrote.
- Handover between team members. When the person who built a feature leaves, what remains is whatever lives in the repo. Chat history does not transfer; a specification does. For teams with turnover, SDD doubles as onboarding documentation.
Our rule of thumb stands: if you cannot answer “who reads this code next month?”, you are vibe coding — make sure that is intentional. This spec-as-contract pattern is also how we build agents for clients; see our AI agents and automation service and our prompt enhancer project.
Adopting SDD does not mean changing the whole way you work in a day. The Spec Kit documentation suggests an incremental path: install with specify init, pick the agent you already use, then run one small feature through the full flow before deciding how far your team adopts it.
How do the two compare on explicit criteria?
The table below is our qualitative assessment — not a measurement, and the criteria are ones we chose:
| Criterion | Vibe coding | Spec-driven development |
|---|---|---|
| Speed to first demo | Very fast; a prompt becomes code directly | Slower at the start; the spec is written first |
| Maintainability | Low; unread code is hard to maintain | Higher; the specification records intent |
| Auditability | Almost no trail beyond chat history | Spec, plan, and tasks persist as artifacts in git |
| Onboarding cost | Nearly zero | Requires learning the flow and the discipline of writing specs |
| Regulated or fintech contexts | A poor fit; no decision trail | A better fit; decisions are documented and reviewable |
One row deliberately missing from this table: “code quality.” We hold no measured evidence that either approach produces fewer defects in general, and we will not invent the numbers.
What are the alternatives between the two poles?
Full vibe coding and a full SDD pipeline are not the only options. Some real alternatives, and when each wins:
- Kiro (AWS). An agentic IDE with built-in specs: a feature is decomposed into
requirements.md,design.md, andtasks.md, with EARS notation for acceptance criteria. It wins when you want SDD structure integrated into one IDE and are willing to use that IDE. - TypeSpec (Microsoft). An API description language for defining the API contract first, then generating code and documentation from it. It wins when what needs pinning down is the shape of an API, not the entire feature-development process.
- AGENTS.md plus plan mode. Standing repo-level conventions (a single AGENTS.md file) combined with a plan mode in your coding agent — the agent drafts a plan and asks for approval before touching files. It wins when a team does not yet need a full pipeline but wants the agent to stop guessing.
- Write the tests first. Tests as the behavioral contract; the agent is directed to make the tests pass. It wins when the desired behavior can be expressed as assertions and the team already has test discipline.
All of them share one idea with SDD: moving intent out of your head and into an artifact that both the agent and humans can read. The difference is only how heavy that artifact is.
When does each one win?
Vibe coding wins when the cost of failure approaches zero and the code’s lifespan is short: exploration, demos, one-off scripts. SDD wins when changes must be auditable, knowledge must outlive the person who wrote it, and the agent needs explicit boundaries. Between the two sits the pattern we see working most often: vibe for exploration, spec before production. Use vibe coding to discover the shape of the solution, then write the specification from what you learned before that code is hardened and maintained. What to avoid is drifting into the middle unconsciously — vibe-coded software quietly becoming a production system without anyone ever writing down its intent.
What does this article not answer?
This article does not establish that SDD produces fewer defects; we ran no controlled comparison, and such claims should not be made without measurement. Star counts measure attention, not fitness for your team. Specifications can also rot: a spec that is not updated when the code changes is worse than no spec, because it lies with confidence. And verifying agent output remains its own discipline — a specification does not replace evaluation, it only gives evaluation a target. That evaluation pattern is what we built in the llm-eval-harness project. Finally, Spec Kit evolves quickly; the command names and flow we cite apply as of the source check on October 1, 2026 and may change in later releases.
If you want to structure AI-assisted development in your team — from repo conventions to evaluating agent output — talk to us.
