Spec-Driven Development Explained: From “Prompt and Pray” to “Spec and Steer”

1. Where the Problem Begins

As coding agents have become more capable, a pattern has emerged: you describe a goal and receive a large amount of code that looks approximately right—but is not quite right. This “vibe coding” approach is excellent for rapid prototypes but unreliable for serious, critical applications.

The 2025 Stack Overflow Developer Survey, covering more than 90,000 developers, found that 66% named “almost right, but not quite” as their greatest frustration with AI tools, while 45% said they spend substantial time debugging AI-generated code.[1]

The problem is not the Agent’s coding ability; it is the input we give it. We treat a coding Agent like a search engine, but it is really an extremely literal pair programmer. It excels at pattern matching but needs clear, unambiguous instructions.

2. Core Definition

Spec-Driven Development treats the specification, not the code, as the source of truth. AI performs far better on structured tasks than on open-ended prompts.[2]

In a spec-driven workflow, the specification drives implementation, testing, and task decomposition. You do not begin writing code until the specification has been validated.[3]

In one sentence: do not ask AI to write code first. Ask it to write a specification, verify that the specification is correct, and then have it implement that specification.

3. Comparison with Vibe Coding

A concrete example illustrates the difference. A vibe-coding prompt is “Build a rate limiter middleware for Express.” A spec-first prompt is “Implement the rate limiter defined in .spec/features/rate-limiter.md, which specifies a sliding window algorithm, 100 requests per minute per API key, 429 responses with Retry-After headers, and Redis-backed state for horizontal scaling.” The second approach leaves no room for the Agent to improvise. Decisions that belong to you are not delegated to the Agent.[4]

The key insight is that both approaches often consume roughly the same total time; they differ in where that time is spent. Vibe coding spends time repeatedly revising code after generation. SDD spends time writing the specification before generation. The specification is reusable and remains useful as documentation after delivery.[4]

Traditional development locks you into early decisions, whereas spec-driven development makes changing direction straightforward: update the specification, regenerate the plan, and let the Agent handle the remaining work.[5]

4. The Four-Stage Workflow

GitHub’s Spec Kit and Addy Osmani’s guide describe essentially the same four-stage model.

Phase 1: Specification

Begin with a high-level prompt, such as “Build a web app where users can track tasks, with user accounts, a database, and a simple UI.” The Agent responds with a structured draft specification containing an overview, feature list, technology recommendations, data model, and so on. This specification becomes the source of truth that both you and the Agent can consult.[3]

A specification is neither a PRD nor an SRS, but a combination of both. Writing it like a PRD ensures that you include user-centered context—the “why” behind each feature—so AI does not optimize in the wrong direction. Extending it like an SRS ensures that you pin down the concrete details AI needs to generate the correct code, such as the database and API to use.[3]

A specification normally includes goals and motivation, user stories, testable acceptance criteria, technical constraints, explicit non-goals, and integration points.

Phase 2: Plan

Ask the Agent to read requirements.md and produce plan.md, a technical implementation plan mapping requirements to design decisions. The crucial point is that you still have not asked it to write code.[1]

The plan answers “how to implement it”: file structure, module decomposition, API design, data model, and dependency choices.

Phase 3: Tasks

The coding Agent decomposes the specification and plan into actual units of work: small, reviewable pieces, each solving one concrete subproblem. Every task should be independently implementable and testable, much like applying TDD to an AI Agent. Instead of “build authentication,” use a concrete task such as “create a user registration endpoint that validates email format."[3]

Phase 4: Implement

The Agent processes tasks one at a time or in parallel. Instead of reviewing a dump of thousands of lines, however, you review focused changes that solve particular problems. The Agent knows what to build because the specification tells it, how to build it because the plan tells it, and what to work on now because the task tells it.[5]

At every stage, your role is not merely to direct but to validate: Does the specification capture what you truly want? Does the plan account for real constraints? Are there edge cases AI omitted?

5. Why Spec-Driven Development Matters More in the AI Era Than in Traditional Development

In traditional development, when a specification is incomplete, a human developer can debug and adapt during implementation. If the authentication service needs a different approach or a package version introduces a breaking change, a person can respond flexibly.

AI agents currently lack that level of adaptive debugging and research. They execute a specification literally, and incomplete research can snowball into implementation failure.[6]

Another key point is that AI-assisted development greatly increases the cost of ambiguity. When an AI Agent participates, unclear intent does not merely slow progress; it actively creates risk. A specification is no longer a helpful suggestion but a constraint.[7]

6. The Specification as a Living Document

Make the specification a living document; do not write it and forget it. Update it whenever you and the Agent make a decision or discover new information. If AI must change the data model or you decide to remove a feature, reflect that in the specification so it remains the ground truth. Treat it as version-controlled documentation.[3]

Good version-control habits matter even more in AI-assisted development. Commit specification files to the repository. This not only preserves history; the Agent can use Git diff or blame to understand changes.[3]

This directly echoes the central point of the harness article: the file system is the Agent’s persistent memory layer. The specification is one of the most important files in that layer.

7. Three Maturity Levels

An arXiv paper from early 2026 describes three distinct levels.[1] Industry practice also falls broadly into these categories:

Level 1: Spec-First—write the specification first and execute manually. This is the process defined in your AGENTS.md: clarify requirements, write a specification, confirm it, and then implement. There is no automation; the process depends on Agent discipline. This is the right starting point for most teams in 2026.

Level 2: Spec-Validated—automated specification validation. Add automated drift detection. If the implementation diverges from the specification, CI fails. Tools such as GitHub Spec Kit and Amazon Kiro belong at this level.

Level 3: Spec-as-Code—the specification is the code. This is the more radical view: the specification is the only artifact that needs maintenance, while code is an automatically generated intermediate artifact. It resembles SQL generating a query plan or Terraform generating infrastructure. This level remains experimental.

8. Today’s Tooling Ecosystem

Leading spec-driven development tools in 2026 fall into two groups: living-spec platforms that keep documentation and code synchronized while an Agent works, and static-spec tools that structure requirements in advance but require manual correction when implementation drifts.[8]

The main tools are:

GitHub Spec Kit (open source, MIT). It provides scaffolding for a spec-driven workflow through a Python CLI, has 72.7k stars, and supports more than 22 AI Agent platforms.[9] It is suitable for greenfield projects.

Amazon Kiro. It implements spec-driven development using EARS (Easy Approach to Requirements Syntax) and integrates deeply with the AWS ecosystem.

AGENTS.md / CLAUDE.md with a manual process. This is what you currently do: implement a spec-first workflow with Markdown files and Agent behavior rules without depending on a particular tool. If you use a methodology-neutral tool such as Cursor or Claude Code, you need to find a workflow that suits you. The core of SDD is moving beyond vibe coding by separating design from implementation.[10]

9. Relationship to What You Already Know

Relationship to Harness Engineering. A specification is part of the harness’s Context Injection layer. It is the most important structured information injected into Agent context. A good specification directly determines the Agent’s behavior throughout the work cycle.

Relationship to the Ralph Loop. The Ralph Loop’s central prerequisite is an explicit completion criterion. Without acceptance criteria in the specification, its verification step cannot determine whether a task is truly complete. When the Ralph article says that “good Agent results come not from a smart model but from writing a good specification,” this is what it means.

Relationship to your AGENTS.md. The Spec-Driven Development section you added implements SDD at Level 1. Agent behavior rules in AGENTS.md + a specification file at specs/FEATURE_NAME.md + acceptance criteria + a confirmation mechanism form a lightweight but complete spec-driven workflow.

10. An Honest Caveat

Experienced programmers may find that overly formal specifications create unnecessary friction and slow cycles of change and feedback, much like the problems encountered in early waterfall development.[10]

Martin Fowler also points out that “neither Kiro nor spec-kit are suited for the majority of real-world coding problems."[11]

The main difficulty with SDD is not AI, but people. SDD requires developers to specify intent precisely, yet that is exactly the greatest challenge. Across more than a decade of software development, few projects have fully clarified their requirements before implementation begins.[12]

This is a real risk. SDD works best for features of moderate or greater complexity. For a one-line fix, a simple refactor, or a rapid prototype, following the entire specification process is overengineering. The intuition to know when a specification is necessary and when to act directly is itself part of engineering experience.

Sources

Recommended Reading

Grouped by topic and arranged from introductory to advanced.

Getting Started: What SDD Is and Why It Is Necessary

• https://developers.redhat.com/articles/2026/02/17/uncomfortable-truth-about-vibe-coding
• https://www.scalablepath.com/machine-learning/spec-driven-development-guide
• https://dev.to/bobbyblaine/spec-driven-development-write-the-spec-not-the-code-2p5o

Core Methodology: How to Write a Specification

• https://addyosmani.com/blog/good-spec/ (also published at https://www.oreilly.com/radar/how-to-write-a-good-spec-for-ai-agents/ )
• https://medium.com/@haberlah/how-to-write-prds-for-ai-coding-agents-d60d72efb797
• https://carlytaylor.substack.com/p/ai-spec-driven-development

Tools and Frameworks: How to Implement SDD

• https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
• https://developer.microsoft.com/blog/spec-driven-development-spec-kit
• https://www.augmentcode.com/tools/best-spec-driven-development-tools
• https://pasqualepillitteri.it/en/news/158/framework-ai-spec-driven-development-guide-bmad-gsd-ralph-loop

Industry Analysis and Trends

• https://thoughtworks.medium.com/spec-driven-development-d85995a81387
• https://medium.com/@visrow/spec-driven-development-is-eating-software-engineering-a-map-of-30-agentic-coding-frameworks-6ac0b5e2b484
• https://thenewstack.io/vibe-coding-spec-driven/
• https://www.javacodegeeks.com/2026/03/spec-driven-developmentwith-ai-coding-agents-the-workflow-replacingprompt-and-pray.html

Complete Vibe Coding Guides, with SDD as a Key Stage

• https://www.gauraw.com/vibe-coding-complete-guide-2026/
• https://www.sitepoint.com/vibe-coding-2026-complete-guide/

Recommended Reading Order

If time is limited, read in this order:

1. Red Hat: The uncomfortable truth about vibe coding — 5 minutes to understand the problem
2. Addy Osmani: How to Write a Good Spec for AI Agents — 30 minutes for the core methodology; the most important article
3. GitHub Blog: Spec-driven development with AI — 15 minutes to understand the four-stage workflow and Spec Kit
4. Drew Maring: How to Vibe Code like a Google Engineer — 20 minutes for one complete practical example
5. ThoughtWorks: Spec-driven development — 15 minutes to understand the industry debate and SDD’s boundaries

The total is under two hours and covers the complete picture from concept to practice to controversy.