Notes on Spec-Driven Development

"Your scientists were so preoccupied with whether or not they could, they didn't stop to think if they should."

— Dr. Ian Malcolm, Jurassic Park

That quote has been living in my head for the past year. It’s the perfect epitaph for the first age of AI-assisted coding, an era defined by a chaotic, exhilarating methodology we’ve come to call "vibe coding." It’s the practice of throwing a vague, conversational prompt at an AI agent and watching, mesmerized, as a functional application materializes from the ether. For rapid prototyping and spinning up a quick proof-of-concept, the speed is intoxicating.

But the initial magic inevitably gives way to a harsh reality. As projects move toward production, the architectural shortcuts and inconsistent patterns generated by an unguided AI begin to compound. The time saved in the initial sprint is quickly consumed by an endless cycle of debugging, refactoring, and trying to decipher the AI's hallucinations, all while the token costs for each regeneration spiral. We were so preoccupied with whether we could generate an entire app from a single sentence that we didn't stop to think if we should.

This post is my map of the necessary course correction that is now taking place: the industry's rapid convergence on Spec-Driven Development (SDD). We'll explore the fundamental architectural philosophies that separate unstructured prompting from disciplined specification. Then, we'll survey the major players in the emerging tooling landscape. My goal is to lay out the core trade-offs to help you navigate this new frontier.

A Tale of Two Architectures: Vibe vs. Spec

The primary schism in AI-assisted development is the method by which we communicate our intent to the agent. This choice dictates whether we act as a hopeful prompter or a deliberate architect.

Figure 1: A comparison of the unstructured, cyclical nature of vibe coding versus the phased progression of Spec-Driven Development.

1. Vibe Coding: The Improvisational Jam Session

This is the free-form, chat-based model that defined our initial interactions with agentic AI. The workflow is a tight, reactive loop: prompt, generate, review, repeat.

Tools: This is the default interaction model for most AI assistants, including the chat interfaces in Cursor, Cline, and GitHub Copilot.

Trade-offs: The velocity for greenfield projects is unmatched. You can move from a blank canvas to a working prototype in hours. However, this approach fails to scale. Without explicit architectural guardrails, the AI's output becomes inconsistent and brittle, creating a mountain of technical debt that undermines the initial speed advantage.

2. Spec-Driven Development (SDD): The Architectural Blueprint

This is a more rigorous methodology where the primary engineering artifact is not the code, but a formal, machine-readable specification that serves as an executable blueprint for the AI. The workflow is a structured, four-phase process designed to ensure clarity and control.

Tools: This is the flagship workflow of Kiro's "Spec Mode" and the core philosophy behind open-source frameworks like Spec Kit.

Trade-offs: The upfront investment in planning and specification writing is significant and can feel slow for simple tasks. However, for complex, production-grade systems, this discipline is essential. It drastically reduces ambiguity and forces a level of architectural foresight that results in higher-quality, more maintainable code from the outset.

Beyond TDD and BDD: A New Contract with AI

To understand what makes SDD a distinct paradigm, it's useful to place it in context with its predecessors.

Test-Driven Development (TDD) is a developer-centric practice focused on code correctness. The cycle is tight: write a failing test, write the minimum code to make it pass, then refactor. It's about building robust units from the inside out.

Behavior-Driven Development (BDD) evolved from TDD to solve a human communication problem. It uses a shared, natural language (like Gherkin's Given-When-Then syntax) to ensure that the software's behavior aligns with business requirements, making it a bridge between technical and non-technical stakeholders.

Spec-Driven Development is different. It was conceived to solve an AI control problem. An AI agent doesn't suffer from human miscommunication; it suffers from a lack of complete and unambiguous instructions. The primary audience for an SDD spec is the machine. Therefore, the specification must be far more comprehensive than a BDD scenario. It must contain not only the desired user-facing behavior (the "what") but also the detailed technical implementation plan (the "how"), including architectural patterns, data schemas, and security constraints. This transforms the specification from a document that describes the software into an executable blueprint that directly generates it.

Mapping the SDD Frontier: A Survey of the Tooling Landscape

The market is rapidly bifurcating into three categories of SDD tools: fully integrated platforms, open-source workflow frameworks, and specialized context providers.

Figure 2: The SDD ecosystem, showing how foundational frameworks and context providers can be used to enable spec-driven workflows in modern AI IDEs.

1. The Integrated Pioneer: Kiro

Amazon's agentic IDE was one of the first major tools to build a polished, end-to-end SDD workflow, effectively defining the market category.

Core Architecture: Kiro's "Spec Mode" guides the developer through a structured process that generates and maintains three interconnected markdown documents: requirements.md for user stories, design.md for technical architecture (complete with Mermaid diagrams), and tasks.md for the implementation checklist. A key feature is that these documents are living artifacts designed to remain synchronized with the codebase, tackling the classic problem of documentation drift.

Enterprise Features: Kiro includes "Agent Steering," a system of persistent markdown files (.kiro/steering/) that provide the AI with institutional memory about project standards, and "Agent Hooks," an event-driven automation framework for tasks like auto-generating unit tests on save.

Positioning: Kiro is a proprietary, all-in-one solution for teams that want a standardized, out-of-the-box SDD process.

2. The Open Foundation: Spec Kit

In response to the market demand that Kiro validated, GitHub released Spec Kit, an open-source, tool-agnostic toolkit designed to bring SDD principles to any AI coding assistant.

Core Architecture: Spec Kit is an MIT-licensed CLI that scaffolds a project with a standardized directory structure and a set of reusable prompts. A key file is /memory/constitution.md, which defines high-level project principles and standards for the AI agent.

Workflow: Instead of being a native IDE feature, Spec Kit provides a set of slash commands (/specify, /plan, /tasks) that a developer uses within their chosen AI tool's chat interface to guide the agent through the SDD phases.

Positioning: Spec Kit is a universal translation layer, providing specific instruction files (.cursorrules for Cursor, CLAUDE.md for Claude-based tools) that allow teams to adopt a standardized SDD process regardless of their preferred IDE.

3. The Context Provider: Tessl

While Kiro and Spec Kit focus on the project's own specification, Tessl addresses a different, but equally critical, problem: an AI's tendency to hallucinate or misuse the APIs of third-party libraries.

Core Architecture: Tessl's central innovation is its "Spec Registry," a repository of over 10,000 machine-readable specifications for popular open-source libraries. When an agent needs to use a dependency, it can pull a structured, reliable spec from the registry instead of relying on outdated training data.

Positioning: Tessl is the "antidote to vibe coding" at the dependency level. It is a complementary layer to tools like Spec Kit. A mature SDD workflow will likely involve using a Spec Kit-like framework to define an application's architecture, which in turn references dependencies whose usage is governed by specs pulled from a Tessl-like registry.

Forging Your Own Path: SDD in Modern IDEs

While Kiro offers a turnkey solution, other leading AI IDEs provide powerful primitives that allow developers to construct their own customized SDD workflows, especially when paired with a framework like Spec Kit.

• Roo Code is a highly customizable, open-source autonomous agent. Its native "Architect Mode" is a natural fit for the "Specify" and "Plan" phases of SDD. For a more advanced setup, developers can create a suite of custom modes to build a bespoke SDD pipeline with specialized agents for each phase.
• Cline is built around transparency and planning. Its built-in "Plan Mode" forces a collaborative planning session with the AI before any code is written, making it ideal for a spec-first approach. Persistent architectural guardrails can be defined in .clinerules files.
• Cursor offers maximum flexibility. While it lacks a native "Spec Mode," its support for custom commands (defined in a .cursor/commands directory) allows developers to build their own SDD toolkit from scratch. The community has already created and shared open-source repositories that replicate Spec Kit's functionality within Cursor.

Finding the Right Gear: A Spectrum of Discipline

The most effective teams will recognize that SDD is not an all-or-nothing dogma. It's a spectrum of discipline that should be applied based on the complexity and risk of the task at hand. The goal is always to provide sufficient clarity to the AI; the amount of ceremony required is variable.

Figure 3: A simplified decision tree for choosing the appropriate level of SDD rigor.

This can be broken down into three practical levels of adoption:

• Level 1: Spec-Informed Prompting. For simple bug fixes or small, well-defined tasks, the full SDD process is overkill. Here, you can apply the spirit of SDD by writing more detailed, structured prompts that include clear context, constraints, and acceptance criteria.
• Level 2: Single-File Specification. For medium-sized features, a lightweight approach is often sufficient. This involves creating a single spec.md file that outlines the feature's goals and technical approach. This file is then passed as context to the AI agent to guide its implementation.
• Level 3: Full SDD Workflow. For large, complex, or high-risk projects—such as building a new service, undertaking a major refactoring, or adding a core feature to an existing system—the full, multi-phase SDD workflow (Specify, Plan, Tasks, Implement) is warranted. This is where tools like Kiro's "Spec Mode" or frameworks like Spec Kit deliver their full value.

The Architect's Era

Spec-Driven Development represents a crucial maturation of our craft. It's the necessary transition from the chaotic, improvisational jazz of "vibe coding" to a disciplined collaboration between human architects and AI implementers. The fundamental insight of SDD is that as AI commoditizes the mechanical act of writing code, the most valuable human contribution shifts upstream to the clear and precise definition of intent.

As Sean Grove of OpenAI has noted, the new scarce skill is "writing specifications that fully capture your intent and values." In this new era, the most valuable engineers won't be the fastest typists; they will be the clearest thinkers. The future of development will not be prompted; it will be specified.