Spec-Driven Development Beats Prompt-and-Pray

Spec-driven development is a workflow where you write the requirements, architecture, and acceptance criteria before an agent writes a single line of code, and the agent implements against that document instead of improvising from a one-line prompt. The spec becomes the executable source of truth. The agent's job is to match it, not guess at it.

I have watched the alternative enough times to know its shape. Someone types a prompt, the agent produces something that compiles and looks reasonable, and three files later nobody remembers what the original requirement was. The demo runs clean. The edge case a customer hits in week two was never specified, so nobody, human or agent, knew to build for it.

Key takeaways

If you only read one section, read this one.

• Spec-driven development means writing the spec first and having the agent implement against it, replacing the prompt-then-patch loop with an interview, a specification, a plan, a task list, and a verification step.
• It exists to fix a specific failure mode. Coding agents are strong at pattern matching and weak at inferring intent, so an undocumented requirement produces code that compiles but solves the wrong problem.
• GitHub's open-source Spec Kit formalizes this into six phases, establish, specify, plan, tasks, implement, and converge, and targets more than 30 coding agents, including Claude Code and GitHub Copilot.
• A good spec names the files and interfaces involved, states what is explicitly out of scope, and ends with a verification step that proves the feature works, per Anthropic's own Claude Code guidance.
• Over-specifying is a real failure mode. A spec detailed enough to remove all ambiguity can take longer to write than the fix it describes, and a spec nobody re-reads goes stale the moment requirements shift.

What spec-driven development is

Spec-driven development is a discipline where the specification, not the prompt, is the thing the agent implements against. You write the requirements, the architecture decisions, and the acceptance criteria first. The agent turns that document into code, and the document is what you review, not just the diff.

Contrast that with what most teams do, sometimes called vibe coding: prompt, watch the agent generate something, notice it is roughly wrong, patch it with another prompt, repeat. Vibe coding works fine for one file and a task you could describe in a single sentence. It falls apart the moment the change spans more than a handful of files or more than one session.

The difference is not process for its own sake. It is where the thinking happens. In vibe coding, the thinking happens live, inside the prompt, and gets lost the moment the session ends. In spec-driven development, the thinking is captured in a document the next session, human or agent, can read cold.

Why prompt-and-pray breaks down past a few files

Coding agents are excellent at pattern recognition and weak at inferring intent they were never given. GitHub's own framing of the problem is blunt: agents "excel at pattern recognition but struggle without clear instructions," which is why generated code often does not compile, solves only part of the request, or drifts from the architecture you wanted (GitHub, 2025).

Context makes this worse across multiple sessions. An agent that reasoned correctly about your auth flow on Monday has no memory of that reasoning on Wednesday unless you wrote it down. Every new session restarts from whatever fits in context, which for a multi-file, multi-day feature is rarely the whole picture.

The result is what I think of as the looks-done problem. Code that compiles, passes the obvious cases, and reads cleanly gets treated as finished, because looking finished is the only signal a quick glance gives you. The gap between looks-done and is-done is exactly where a missed requirement hides, and it usually surfaces after a customer finds it, not before.

That gap has a cost past engineering time. A feature that ships against the wrong requirement does not just need a second sprint. It costs the trust of whoever was waiting on it, and trust is the expensive thing to rebuild.

The five-phase loop: interview, specify, plan, tasks, implement

The workflow I use starts before any tool-specific command: an interview. Before a large feature, I have the agent ask me about technical implementation, UI and UX decisions, and edge cases, the way Anthropic's own Claude Code guidance recommends, and only then write a complete spec to a file before implementation starts (Claude Code best practices).

From there, GitHub's Spec Kit formalizes the rest into a repeatable sequence: specify, plan, break into tasks, then implement. In practice, once the interview has produced a spec, it is four commands.

Spec Kit's own documentation describes six phases end to end: establish a constitution for the project's non-negotiables, specify the feature, plan the technical approach, break the plan into tasks, implement, then converge the codebase against the spec (GitHub Spec Kit). The toolkit is MIT-licensed, installs through uv from PyPI, and targets more than 30 coding agents across CLI and IDE environments, not just Copilot and Claude Code.

I walk through this loop phase by phase, with the failure modes at each step, in The Spec Is the Program.

What a good spec contains

A spec vague enough to mean anything will be implemented as whatever the agent guesses first. Anthropic's criteria for a spec worth implementing against are specific: it "names the files and interfaces involved, states what is out of scope, and ends with an end-to-end verification step that proves the feature works" (Claude Code best practices).

In practice, that means a spec should answer four questions before the agent starts:

• Which files and interfaces does this touch? Name them. "The export endpoint" is not a file; src/api/exports.ts is.
• What is explicitly out of scope? An agent will happily "improve" a neighboring function unless you tell it not to.
• What does correct behavior look like on the edge cases? Empty input, permission denial, the row limit. Name the ones that matter for this feature.
• What proves this works when it is done? A test that passes, a build that exits clean, a screenshot that matches the design. Something the agent can check itself against, not just describe.

Anthropic's own summary of the trade-off is worth repeating exactly: time spent making the spec precise pays off more than time spent watching the implementation happen.

Give the agent a way to verify itself

The verification step is what closes the loop. Without one, an agent stops when the work looks done, and looking done is the only signal it has. With one, it has a pass or fail result to check itself against before handing the diff back to you.

Picture a spec for a CSV export feature that ends with a single instruction: run the export against a workspace with mixed permission levels, confirm the output contains only rows the requesting user can see, and confirm the build exits clean. That one sentence gives the agent something to run, not just something to read.

Tests are the obvious check. A build exit code is a cheaper one. A screenshot compared against the design is a check for UI work that no unit test would catch. Pick whichever check maps to the requirement, and put it in the spec itself, not in a separate ticket the agent never sees.

This is also where the discipline connects to what happens after implementation. A spec with a real verification step still needs a second, fresh pair of eyes on the diff before it ships, which is the review discipline I cover in AI code review.

Where this breaks: over-specifying and spec rot

Spec-driven development has its own failure mode, and it is worth naming honestly instead of selling the process as free discipline. The first is over-specification: writing a spec detailed enough to remove every ambiguity can take longer than watching the agent code and correcting it as you go.

The second is spec rot. A spec written once, at the start of a two-week feature, does not update itself when the requirement shifts on day four. The agent keeps implementing against the original document while the actual need has moved, and nobody notices until review, because nobody went back and re-read the spec.

The real skill is not writing exhaustive specs. It is calibrating how much detail a task needs. Anthropic's own guidance draws the line plainly: skip planning entirely if you could describe the diff in one sentence (Claude Code best practices). A one-line bug fix does not need a requirements document. A new subsystem does.

I treat spec length as a function of blast radius, not a fixed template. A change confined to one function gets a sentence. A change that touches a data model, an API contract, and three consumers of that API gets the full loop, interview included.

Tools built for this today

Three tools cover most of what teams use for this right now.

AWS positions the pitch precisely: developing with specs "keeps the fun of vibe coding, but fixes some of its limitations" (Kiro). That is close to how I would describe it too. You do not lose the speed. You lose the part where the speed was deferred rework, the kind that shows up later as the gap between AI-assisted habits and an AI-native workflow.

How to start on your next feature

Do not roll this out as a company-wide process change. Pick your next feature that touches more than two files, and write the interview answers down before you open an agent session: what files it touches, what is out of scope, and what proves it works when it is done. That is the whole spec.

Run the loop once, watch where it saved you a redo and where it felt like overhead, then adjust the level of detail for the next one. This fits inside the larger shift I map out phase by phase in the AI SDLC, where spec-writing becomes the front door for everything an agent builds downstream.

Frequently asked questions

What is spec-driven development in AI coding?

It is a workflow where you write the requirements, architecture, and acceptance criteria before an agent implements anything, and the agent builds against that document instead of a short prompt. The spec, not the diff, is what you review and defend.

Is spec-driven development the same as vibe coding?

No, and they solve different problems. Vibe coding is prompt, generate, notice it is wrong, patch, repeat, which works for small, single-session changes. Spec-driven development front-loads the thinking into a document so an agent can handle multi-file, multi-day work without drifting off the actual requirement.

How detailed should a spec be before I let an AI agent implement it?

Detailed enough to name the files and interfaces involved, state what is out of scope, and end with a verification step that proves the feature works. No more than that. If you could describe the change in one sentence, skip the formal spec and say the sentence.

What tools support spec-driven development right now?

GitHub Spec Kit, AWS Kiro, and Claude Code's plan mode are the three in active use today. Spec Kit is the most tool-agnostic of the three, targeting more than 30 coding agents; Kiro and Claude Code build the discipline into their own CLI and IDE experience.

The teams that get real leverage from an AI coding agent are the ones that stopped treating the prompt as the spec. If your last feature shipped past QA and still needed a week of fixes nobody predicted, the fix probably is not a better prompt. It is a spec an agent can implement against and a check it can run to prove the work is done, the kind of build discipline ViitorCloud's product engineering team puts in place before the first line of code ships.