Spec-driven development: from vibe coding to team memory

“Vibe coding” started as an offhand tweet and ended up as word of the year. Andrej Karpathy coined the term on February 2, 2025^[1]: give in to the vibes and forget that code exists. Twelve months later he described it himself as “a shower of thoughts throwaway tweet”^[2]. Along the way, Collins Dictionary crowned it word of the year 2025^[3], while GitHub Spec Kit — which pushes the exact opposite — went from oddity to 117,000 GitHub stars^[4].

Seventeen months of hype and hangover that have settled into something like a practice. Nobody planned it. If your team is shipping agent-generated code faster than ever, but every session starts from zero and nobody trusts the output, this is your topic. Spec-driven development proposes an idea that’s uncomfortable for anyone who enjoys improvising: think first, type later. Here’s why I think that discomfort is exactly what you were missing.

Why does vibe coding collapse the moment you have to maintain something?

Vibe coding collapses because the context holding it up never gets written down anywhere: it lives in the head of whoever is prompting and in the agent’s session, and it evaporates the moment you close the tab.

Let me be clear, because I don’t want to build a strawman here: for a prototype, it works, and works well. In 25% of Y Combinator’s Winter 2025 cohort, an LLM generated 95% of the code lines^[5]. Garry Tan celebrated it in March 2025: “the age of vibe coding is here.”

The problem shows up later, when that prototype needs to be maintained. A Cloud Security Alliance research note from April 2026 aggregates industry data, and the picture is grim: AI-assisted developers commit at three to four times the rate, but introduce security findings at ten times the rate. 45% of AI-generated code samples carry OWASP Top 10 vulnerabilities, and there are already 74 CVEs attributed to AI tools^[6].

Vibe coding works for what it’s meant for; it becomes unmaintainable without a control artifact. The very cohort Tan was celebrating is the context for that hangover: speed without memory.

What if the “vibe” is lying to you about your speed?

The feeling of going fast isn’t evidence of going fast. In METR’s controlled trial, published in July 2025, sixteen experienced open-source developers worked through 246 tasks in mature repos. With AI allowed, they took 19% longer. The damning part is the perception gap: they expected to go 24% faster, and after finishing, still believed they’d gone 20% faster^[7].

METR itself warns that the result doesn’t generalize to every developer or every domain: these were huge repos, with over a million lines and years of accumulated context. Even with that caveat, the pattern is uncomfortable. The “vibe” tells you one thing and the stopwatch tells you another.

Google’s DORA 2025 report arrives at the same place by a different road. AI adoption hit 90%, over 80% report a productivity improvement, but 30% trust the code it generates “little” or “not at all”^[8]. DORA describes AI as a mirror and a multiplier: if your process is already disciplined, it amplifies that; if it’s chaos, it amplifies the chaos.

The answer to this self-deception is to measure, not to trust the feeling. If you want to trade impressions for evidence, that work is covered in how to evaluate AI agents in production and in treating every improvement as an experiment with telemetry, as I explain in this methodology for agents that improve themselves. A spec with explicit validation criteria is the minimal version of that idea.

What exactly is spec-driven development?

Spec-driven development reverses the order of vibe coding: instead of jumping straight to implementation, you do the hard thinking work first and document it in a specification versioned in the repo that agents read as a contract.

Mariya Mansurova defined it precisely in Towards Data Science: do the hard thinking work first (architecture decisions and non-negotiables) and document it in a markdown spec stored in the repository and kept up to date alongside the project^[9]. The idea behind this post’s title is hers: the spec preserves context “across sessions and even across different AI agents.” That’s the core idea. The spec is the team’s persistent memory.

GitHub Spec Kit takes this to the operational extreme. Its README puts it bluntly: “specifications become executable, directly generating working implementations rather than just guiding them”^[4]. It’s a slash-command workflow, already in production, that supports more than 30 coding agents, from Claude Code to Cursor.

# Flujo de GitHub Spec Kit: de los principios al código
/speckit.constitution   # fija los principios y no-negociables del proyecto
/speckit.specify        # define QUÉ se construye y por qué
/speckit.plan           # traza el plan técnico de implementación
/speckit.tasks          # descompone el plan en tareas accionables
/speckit.implement      # el agente ejecuta contra la spec

Put side by side, the balance of forces is clear:

	Vibe coding	Spec-driven development
Where the context lives	In your head and in the agent’s session	In the repo, versioned in git
Initial speed	Maximum — you start instantly	Lower: you pay the cost of thinking first
Across sessions and agents	Evaporates when you close the tab	Persists; any agent can re-read it
What you can delegate	Little, and with constant supervision	Bounded slices with a verifiable contract
When it pays off	Prototype, spike, throwaway work	Anything that needs maintaining or touches more than one person

Is this waterfall reincarnated?

No, and the difference is in the length of the feedback loop. It’s the number-one objection from any senior who lived through waterfall, and it’s a legitimate one. Liu Shangqi, from Thoughtworks, distinguishes two flavors of spec-driven development^[10]. In the radical flavor, the spec is the single source of truth and the code is disposable: you regenerate the implementation every time the spec changes. In the conservative flavor, the spec guides generation but the code still rules, with CI/CD as the referee.

My position is that today only the conservative flavor survives contact with production. Liu makes the case well: spec-driven development doesn’t create huge feedback loops like waterfall — instead it offers a mechanism for loops that are shorter and more effective than pure vibe coding would allow. The spec doesn’t freeze the design for six months. It gets updated in the same PR as the change that invalidates it.

The symmetric risk also exists: an over-formalized spec slows change down instead of enabling it. And a new failure mode shows up — “spec drift”: the spec stops reflecting the system and agents generate against a false contract. It’s the same old doc-rot, and you fight it the same way as with code: review it on every PR and let CI fail when the spec and the implementation diverge.

What does a useful spec contain (and what doesn’t it)?

A useful spec describes the software’s external behavior and leaves the how to the agent. Thoughtworks makes it concrete: input/output mappings, preconditions and postconditions, invariants, constraints, and integration contracts^[10]. Mansurova adds the intent layer: the non-negotiables and architecture decisions, a set of “constitutional” documents that change rarely (mission, tech stack, roadmap, and design principles) and, per feature, a spec with its requirements and validation criteria^[9]. And WeBuild-AI insists on two sections almost nobody writes and everybody misses: the existing implementations the feature relates to, and the security standards that apply to it^[11], including those covering the supply chain of skills and MCP servers your agent runs when implementing it.

Put together, it looks like this. Here’s the skeleton I use for a webhook retry worker — the classic service nobody wants to touch blind ever again:

# Spec: webhook retry worker

## Goal
Redeliver failed webhooks without duplicating deliveries that are already confirmed.

## External behavior (I/O)
- Input: event on the `webhooks.dead` queue with its payload and attempt count.
- Output: POST to the client's endpoint; marks the event `delivered` or `exhausted`.

## Invariants and non-negotiables
- Never resend an event that's already confirmed (idempotency by `event_id`).
- Maximum 5 retries, with exponential backoff.
- No secrets or PII in the logs, ever.
- An exhausted event never goes back into the active queue.

## Integration contracts
- Reads from `webhooks.dead` (v2 format). Writes metrics to `delivery_stats`.

## Validation criteria
- A confirmed event is never resent, even if it reappears in the queue.
- On the 6th failure the event becomes `exhausted`, never loops forever.

## Out of scope
- Onboarding new client endpoints (covered by a different feature).

Where it lives: in the repo, next to the code, versioned in git like any other file. How it evolves: it gets updated in the same PR as the change that makes it obsolete, never “whenever there’s time.” Pay attention to the validation criteria section, because that’s where the spec hooks into the tests. Those criteria are the contract that your testing strategy for AI-generated code actually enforces. And the non-negotiables at the very top are the same ones you already work through when designing an agent: if you haven’t nailed those down yet, start with the decisions that define an enterprise agent’s architecture.

What a spec doesn’t contain is implementation detail. If you dictate the how to the agent line by line, you’re back to the giant prompt and you’ve lost the spec. And for a small change, writing a full spec is, in Mansurova’s words, “probably overkill”^[9].

Spec-driven and context engineering: two halves of the same thing

The spec and context management aren’t competitors: they’re two halves of the same solution. Ben Saunders puts it unambiguously on WeBuild-AI: “neither can succeed without the other”^[11]. Spec-driven development without context management produces specs the agent can’t execute well, because it never gets the right information at the right moment. And context management without a spec is, in his view, sophisticated infrastructure with no clear destination: you know how to serve context, but not toward what goal.

My reframe is simpler. The spec is stable context engineering. It’s context that doesn’t get rebuilt every session: it persists and it’s versioned. When you write a spec, you’re deciding what information deserves to survive the closing of the tab.

What changes in your role if you adopt spec-driven development?

Adopting spec-driven development shifts your work from writing the implementation to defining and verifying the contract. Anthropic’s “2026 Agentic Coding Trends Report” puts a number on the tension: developers already use AI for around 60% of their work, but can only fully delegate between 0 and 20% of tasks^[12]. That gap between “I use it for almost everything” and “I barely let go of any of it” — the delegation gap I already broke down in depth — is where spec-driven development lives. Anthropic describes the primary human role as orchestrating the AI agents that write code, evaluating their output, providing strategic direction, and making sure the system solves the right problem. The spec is the artifact that widens the delegable slice: it turns constant active supervision into a verifiable contract plus a review.

In The Pragmatic Engineer, a survey of more than 900 engineers captures what this looks like day to day. One engineer describes it this way: paste the acceptance criteria and the issue description into plan mode, let the model work through it, then hand off to Composer or Sonnet for the agent to take over^[13]. The acceptance criteria are, once again, the spec in miniature.

Mansurova sums it up: the engineer’s role shifts “from writing code directly to focusing more on architecture decisions, review, and system design”^[9]. The spec is what defines the contract that closes the agent’s loop, the piece that turns an agentic loop into something with a verifiable stopping criterion instead of an emotional progress bar.

That work has a name: directing agents with judgment. Knowing what to ask for and how to verify the output is a skill, not a gift, and it’s exactly what the course “Design Patterns for AI Agents” trains. The spec demands it; the course teaches it.

Common mistakes that turn the spec into theater

Spec theater: writing it after the code

Writing the spec after the feature is already merged, just to check the ritual box, is the most common mistake and the most useless one. A spec that documents what already exists isn’t memory or a contract: it’s the minutes of a meeting that already happened. Its value is in writing it before, while it still forces you to decide something.

Spec drift: the contract that lies

The spec stops reflecting the system, and agents start generating against a false contract. I’ve seen it in my own repo: you bump the retry limit in the code and the spec keeps saying five, so the next agent that reads it generates against a number that no longer exists. Thoughtworks warns that spec drift and hallucinations are inherently hard to avoid^[10], which is why it insists on deterministic CI/CD. The antidote is mechanical: the spec gets touched in the same PR as the code that invalidates it, or CI rejects it.

# In the SAME PR that raises the retry limit
## Invariants and non-negotiables
- - Maximum 5 retries, with exponential backoff.
+ - Maximum 8 retries, with exponential backoff.

Over-formalization

Writing exhaustive specs for everything slows change down instead of enabling it — the symmetric risk Thoughtworks points to. For a minor improvement, the spec is overkill.

A spec with no validation criteria

It describes the what but not how to check it, and the “vibe” sneaks back in through the back door. Without verification, your perception of speed is worthless — exactly what METR showed. If the validation section is empty, you’ve written an intention and called it a contract.

Dictating the how, not the what

When the spec drops to the level of “use a for loop instead of a map,” it stops being a behavior contract and turns into micromanaging the agent. Fix the external behavior and the invariants; the how is the model’s problem. And if you don’t trust the how, that’s where tests come in, not more lines of spec. Tuning specific instructions is a different discipline: that’s prompt engineering patterns, and they operate one level below the contract.

Checklist: does your spec work as team memory?

• The spec lives in the repo and is versioned in git like the code.
• It fixes external behavior and invariants, not implementation detail.
• It includes validation criteria a test can execute.
• It gets updated in the same PR as the change that makes it obsolete.
• It documents the non-negotiables and architecture decisions before code gets written.
• For a small, single-session change, you’ve consciously decided not to write one.

Sources

1. “Vibe coding” — Andrej Karpathy (X) — the original tweet that coined the term (Feb 2, 2025).
2. Karpathy’s retrospective (X) — “a shower of thoughts throwaway tweet,” a year later.
3. Word of the Year 2025 — Collins Dictionary — “vibe coding,” word of the year 2025 (CNN coverage).
4. GitHub Spec Kit — 117k stars (July 2026), a slash-command workflow, and the quote “specifications become executable.”
5. A quarter of startups in YC’s current cohort… — TechCrunch — 25% of the W25 cohort with ~95% LLM-generated code (Garry Tan’s tweet).
6. AI-Generated Code Vulnerability Surge — Cloud Security Alliance — commits 3-4x, findings 10x, 45% OWASP Top 10, 74 CVEs (Apr 4, 2026).
7. Measuring the Impact of Early-2025 AI on Experienced OS Developers — METR — a 19% slowdown against a perceived +20% speedup (paper).
8. State of AI-assisted Software Development — Google DORA 2025 — 90% adoption, 30% trust it little or not at all, AI as “mirror and multiplier.”
9. From Vibe Coding to Spec-Driven Development — Mariya Mansurova, Towards Data Science — SDD definition, spec contents, and the role shift (May 12, 2026).
10. Spec-driven development: unpacking 2025’s new engineering practices — Liu Shangqi, Thoughtworks — the two flavors of SDD, anti-waterfall, spec drift, and what defines a spec.
11. Aligning Spec-Driven Development and Context Engineering for 2026 — Ben Saunders, WeBuild-AI — “neither can succeed without the other” and the sections of a spec.
12. 2026 Agentic Coding Trends Report — Anthropic — AI in ~60% of the work, 0-20% fully delegable, the orchestration role (PDF).
13. The impact of AI on software engineers in 2026 — The Pragmatic Engineer — survey of 900+ engineers; the acceptance-criteria → plan mode → agent workflow.

Frequently Asked Questions

Is spec-driven development the same as waterfall?

No. Waterfall creates one single giant feedback loop between specifying and delivering; spec-driven development does the opposite, with short, frequent loops, as Thoughtworks argues. The spec doesn’t get frozen at the start of the project: it gets updated in the same PR as the code that changes it.

Do I need GitHub Spec Kit to do spec-driven development?

No, though it helps. A spec is just markdown versioned in the repo: you can set that up without installing anything. Spec Kit adds a slash-command workflow and convenient conventions, and it’s still very active as of July 2026, with more than 117,000 stars. It’s a convenience, not a requirement.

Is it worth writing a spec for a small change?

Almost never. For a minor improvement, writing a full spec is, as Mansurova puts it, “probably overkill”^[9]. The practical threshold is simple: if the work needs to be maintained and more than one session or more than one agent will touch it, the spec pays off.

How is a spec different from an AGENTS.md or a CLAUDE.md?

The context file describes the whole project and its conventions in a stable way: how it’s built and what conventions it follows. The spec fixes the contract for one specific feature: its external behavior, its invariants, its integration contracts, and the criteria it’s validated against. They complement each other, and if you haven’t nailed down your context file yet, start with how an AGENTS.md can wreck or save your agent.

Is the source of truth the code or the spec?

The code, for now. My position is the conservative flavor: the spec guides generation, but the code still rules and CI arbitrates when they diverge. The radical flavor, where the spec is the only truth and the code is disposable, still doesn’t survive contact with a real production pipeline.