Spec Driven Development: What It Is and What It Proposes

The context: from vibe coding to productive chaos

To understand Spec-Driven Development (SDD), or in plain terms: specification-guided development, it helps to start with the problem it tries to solve. In February 2025, Andrej Karpathy (co-founder of OpenAI and former AI director at Tesla) coined the term vibe coding in a tweet that went viral:[1]

"There's a new kind of coding I call 'vibe coding', where you fully give in to the vibes, embrace exponentials, and forget that the code even exists. [...] I 'Accept All' always, I don't read the diffs anymore. When I get error messages I just copy paste them with no comment, usually that fixes it."

For weekend projects and quick prototypes, letting AI take the wheel can work, but it has limitations: code that looks correct but has subtle bugs, inconsistent architectures, security vulnerabilities, and the discomfort of not knowing the logic the generated code implements.

The data is telling: according to Y Combinator, 25% of the startups in its winter 2025 batch had codebases generated 95% by AI.[2] That sounds impressive, unless you ask: who understands and maintains that code?

What Spec Driven Development is

Spec Driven Development proposes, in essence, that the specification precede and guide the code. It is not a framework or a prescriptive methodology like Scrum. It is rather a way of working that proposes:

1. Writing a clear specification first of what you want to build: objectives, business rules, acceptance criteria, technical constraints.

2. Using that specification as the source for both humans and AI agents.

3. Generating code from the spec, not from improvised prompts.

As GitHub sums it up in its Spec Kit documentation: "In this new world, maintaining software means evolving specifications. [...] Code is the last-mile approach."[3]

The three levels of SDD

Birgitta Böckeler, of Thoughtworks, proposes a useful taxonomy for understanding the different implementations:[4]

• Spec-first: You write the spec before coding, use it for the task at hand, and then discard it. It is the most basic level.

• Spec-anchored: The spec is kept after the task is completed and is used for the evolution and maintenance of the feature.

• Spec-as-source: The spec is the primary artifact. You only edit the spec, never touching the code directly. The code is regenerated from the specification.

Most current tools operate at the spec-first level, some aspire to spec-anchored, and only a few experiment with spec-as-source (such as Tessl Framework).

The relationship with AI: the catalyst of the resurgence

Although the idea of "specifying before coding" is at the origin of software engineering, SDD is resurfacing because LLMs need structured context to generate coherent code.

When a coding agent is given a vague prompt like "make me a login", it is guessing the architecture, patterns, validations, and error flows. When it is given a detailed specification that defines exactly what must happen, the resulting code is much more likely to do what you need.

The spec works as a persistent, versionable "super-prompt". As the Kiro team (AWS) describes it: "A specification is a kind of super-prompt (versioned, human-readable)."[5]

Tools in the ecosystem

The SDD tools ecosystem is growing rapidly:[6]

• GitHub Spec Kit: Open source toolkit that provides a structured workflow: Constitution → Specify → Plan → Tasks → Implement. Works with Copilot, Claude Code, and others.

• Kiro (AWS): VS Code-based IDE with an integrated Requirements → Design → Tasks workflow.

• Tessl Framework: Explores the spec-as-source level with a 1:1 mapping between specs and code files.

• BMAD Method: Uses virtual agents (Analyst, Product Manager, Architect) to generate PRDs and architecture specs.

SDD, TDD, and BDD: close cousins, not competitors

If you work with agile methodologies, you probably wonder how SDD fits with practices you already know. The good news: they are not mutually exclusive, they are complementary.[7]

• TDD (Test Driven Development): Tests first. You write a test that fails, then the code to make it pass. Excellent for unit-level quality, but it does not capture the full product intent.

• BDD (Behavior Driven Development): Behavior first. Scenarios in Given-When-Then format that describe how the system behaves. Strong for alignment with stakeholders, but it leaves technical decisions open.

• SDD (Spec Driven Development): Specification first. It defines the what and the why, adds a technical plan, and breaks work down into tasks. The spec is the anchor that keeps everyone (humans and agents) aligned.

In practice, you can use SDD to define the complete feature, TDD for each individual task, and BDD for end-to-end validations. As Beam.ai says: "SDD tells you what and why. BDD verifies behavior across the whole system. TDD ensures correctness at the code level. These practices work well together."

The tension with Agile (and how to resolve it)

Here comes the uncomfortable question: the Agile Manifesto says "working software over comprehensive documentation". Doesn't SDD contradict that principle by asking for detailed specifications upfront?

The short answer: it depends on how you implement it.

The long answer: SDD does not propose extensive, waterfall-style documentation. It proposes living, executable, and versioned specifications that evolve with the code. As GitHub describes it: "Spec-Driven Development is not about writing exhaustive requirements documents nobody reads. Nor is it about waterfall planning."[3]

In practice, SDD works well at the feature or sprint level. You are not specifying the entire product in advance; you are specifying the next functionality in enough detail for an AI agent to implement it correctly.

Critical considerations and limitations

No approach is perfect. These are the most relevant considerations in professional discussions:

The human problem

As Daniel Sogl points out on DEV Community: "The main problem is not the AI, it is the human factor. SDD requires developers to specify their intentions precisely. [...] After more than 10 years in software development, I have rarely experienced projects where the requirements were fully formulated before implementation."[8]

Writing good specs is hard. It requires clarity of thought, domain knowledge, and the discipline to think before acting.

Overhead vs. benefit

Birgitta Böckeler of Thoughtworks tested several SDD tools and found that for small tasks the process was disproportionate: "When I asked Kiro to fix a small bug, the requirements document turned it into 4 'user stories' with 16 acceptance criteria [...] It was like using a sledgehammer to crack a nut."[4]

SDD makes the most sense for medium to large features where the upfront investment pays off through fewer later corrections.

False sense of control

Context windows are larger, but that does not mean the AI follows every instruction. Böckeler observed: "I frequently saw the agent not following all instructions. [...] I also saw the agent overdoing it because it followed instructions too eagerly."[4]

Specs help, but they do not eliminate the non-determinism of LLMs. You still need to review and validate.

Reviewing markdown or code?

Some tools generate massive numbers of markdown files. As Böckeler comments: "Honestly, I would rather review code than all these markdown files. [...] They were repetitive and tedious to review."[4]

A good SDD tool should provide a genuinely better spec review experience than reviewing code, not a worse one.

So, is it worth it?

As with any emerging practice, the honest answer is: it depends.

SDD will probably benefit you if:

• You regularly work with AI coding agents
• Your projects have medium-to-high complexity
• You value traceability and living documentation
• Your team can invest time in learning a new workflow

You probably don't need it if:

• You only build quick prototypes or personal projects
• Your work consists mainly of small fixes and maintenance
• You prefer direct, granular control over every line of code

If you decide to try it, the advice from the AI Native Dev team is pragmatic: "Start with one feature. Don't specify your entire application. Pick a well-understood feature and write a detailed spec. See how your AI agent performs."[9]

Conclusion

Spec Driven Development represents a serious attempt to bring structure to the productive chaos of AI-assisted development. It is not a formal framework, but a philosophy that proposes: define first what you want to build, with enough detail for both humans and agents to work aligned.

The term is still evolving (some already talk about "semantic diffusion"[4]), the tools are experimental, and there are legitimate debates about its applicability. But the underlying principle—think before generating, specify before implementing—is as valid today as it was before LLMs existed.

As the AI Native Dev team summarizes: "We are all figuring this out together, and the patterns that emerge will come from shared experiences across hundreds of teams."[9]

If you work with AI to generate code, it is worth experimenting with SDD, even informally. At the very least, it will force you to think more clearly about what you really want to build. And that, with or without AI, is always good practice.

Cited sources

[1]: Andrej Karpathy on X (Twitter), February 2, 2025: x.com/karpathy/status/1886192184808149383 [2]: "Vibe coding" - Wikipedia. Y Combinator data: es.wikipedia.org/wiki/Vibe_coding [3]: GitHub Blog - Spec-driven development with AI: github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai [4]: Birgitta Böckeler, Thoughtworks - Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl: martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html [5]: Kiro - The future of AI spec-driven software development: kiro.dev/blog/kiro-and-the-future-of-software-development [6]: Microsoft for Developers - Diving Into Spec-Driven Development With GitHub Spec Kit: developer.microsoft.com/blog/spec-driven-development-spec-kit [7]: Beam.ai - Spec Driven Development: The Future of Building with AI: beam.ai/agentic-insights/spec-driven-development [8]: Daniel Sogl - Spec Driven Development: A initial review, DEV Community: dev.to/danielsogl/spec-driven-development-sdd-a-initial-review-2llp [9]: AI Native Dev - Spec-Driven Development: 10 things you need to know about specs: ainativedev.io/news/spec-driven-development-10-things-you-need-to-know-about-specs