Spec-Driven Development: Moving Beyond Vibe Coding for More Reliable AI-Generated Code

In an era where AI coding assistants have become mainstream, more and more developers are running into the same problem: "vibe coding" is fast, but the code quality is inconsistent and often requires significant rework. AWS Senior Developer Advocate Erik Hanchett has proposed a systematic solution — Spec-Driven Development. This article breaks down the core philosophy, key practices, and the Kiro tool AWS built specifically for this approach.

Background: What is "Vibe Coding"? The term "vibe coding" was coined by Andrej Karpathy in early 2025 to describe a style of programming that relies heavily on AI-generated code, where developers rarely read or deeply understand the code details. Its rise is closely tied to the widespread adoption of AI coding tools like GitHub Copilot, Cursor, and Claude. The central tension with vibe coding is this: it dramatically lowers the bar for writing code that "runs," while simultaneously blurring developers' grasp of code intent and boundaries — causing technical debt to accumulate almost invisibly.

What Is Spec-Driven Development

Spec-Driven Development is straightforward to define: create structured specification documents before writing any code. Concretely, you write requirements and design documents in Markdown files first, then let AI implement the code.

Spec-Driven Development didn't emerge from thin air. Its intellectual roots trace back to the "Design First" principle and formal methods in traditional software engineering. In the API space, the "API First" development model driven by OpenAPI/Swagger specifications has been widely practiced for years. Spec-Driven Development extends this philosophy into AI-assisted programming: by making requirements and design explicit and structured, it provides large language models with a verifiable "contract" that constrains their generation behavior. This is directly aligned with the prompt engineering principle of "giving models clear roles and constraints."

Erik notes that this workflow pairs surprisingly well with LLMs and coding assistants. The reason: it front-loads and makes explicit the "requirements" step — the stage most prone to ambiguity and most likely to be misunderstood by AI. Once requirements and design are locked down in document form, AI has a clear "blueprint" to work from rather than guessing at your intent.

There's a key insight here: why not just rely on increasingly capable frontier models? Erik is candid: models do keep improving — sometimes incrementally, sometimes in leaps — but they're still imperfect. Giving a model more context is fundamentally about "pointing it in the right direction." Software requirements are always evolving, new paradigms and technologies keep emerging, and you'll always need a mechanism to steer AI toward the right outcome.

Why This Workflow Works: Treating AI Like an Intern

Erik uses a fitting analogy: think of LLMs and coding assistants as "AI interns." They need proper guidance and direction — give them too much freedom and they'll easily go off the rails.

He recalls his own experience as an intern at his first job: a VP would casually throw out ideas, and young Erik would immediately drop everything to execute on them. His direct manager eventually taught him: write it down, schedule it, align with leadership — don't just blindly follow through. Today's LLMs are exactly like that overeager intern — they'll execute every vague instruction you give them without hesitation.

Spec-Driven Development is the "discipline tool" that addresses this problem: it forces human confirmation of requirements and design documents before AI writes a single line of code. The human remains the center of the loop at all times.

Three Key Considerations in Practice

Drawing from years of experience, Erik shares several things to keep in mind when practicing Spec-Driven Development:

1. The Goldilocks Zone for Context

Although Spec-Driven Development feeds the model a lot of context, even good things can be overdone. When configuring initial files like agents.md or cloud.md, you don't want to stuff in too much information, but too little won't work either — you need to find that just-right "Goldilocks zone."

This phenomenon has deep technical implications: LLMs' attention mechanisms exhibit a "Lost in the Middle" effect when processing very long contexts — research shows models pay significantly more attention to information at the beginning and end of an input sequence than to content in the middle. As a result, injecting too much context not only increases inference cost and latency, but can cause the model to "forget" critical instructions or get lost in the noise. This is precisely why steering document design requires careful tradeoffs: specific enough to eliminate ambiguity, concise enough to maintain the model's effective attention.

In Kiro, these files are called "steering docs" — you simply provide enough rules and guidelines to let AI know how to proceed.

2. Make Good Use of Skills

Erik strongly recommends using Skills — on-demand instruction files. These typically contain keywords that activate the corresponding skill automatically when the coding assistant recognizes them, or you can invoke them manually with slash commands. Skills can be called in parallel when generating design documents or implementing tasks.

3. Don't Over-Trust AI

This is the most important point: throughout the entire process, you are the code reviewer. You need to interactively check the generated design and requirements documents, because when something goes wrong, it's the human — not the AI agent — who is held accountable. That doesn't mean rejecting tools outright — you can absolutely use standard AI review tools to help review every PR — but the responsibility for final sign-off rests with you.

Kiro: AWS's Spec-Driven Development Tool

AWS observed a large number of teams failing to get ideal results from vibe coding, and decided to productize the pattern of "having agents generate complete requirements and design documents" — which developers had previously been cobbling together on their own. Kiro was born from this. After its general availability (GA) release, it's a brand-new AI IDE coding assistant that also offers a popular command-line (CLI) version. Erik notes that users are gradually shifting from the IDE to the CLI.

Kiro's core highlight is its dual-track design with vibe mode and spec mode. After launch it gained significant traction, racking up tens of thousands of downloads — so much so that a waitlist was needed during preview to throttle demand — though people quickly found workarounds. Kiro is now publicly available at kiro.dev, where anyone can download the CLI or IDE to try it out.

It's worth emphasizing: you don't need Kiro to practice Spec-Driven Development. You can do it manually: have the assistant generate user requirements, then generate a design document, then generate an implementation task list — with you reviewing and confirming each step. Erik also gave a shoutout to spec-kit, an open-source GitHub project that can be installed into multiple coding assistants.

Complete Workflow Breakdown

Erik demonstrated the complete workflow using a movie database website as a demo:

Requirements Phase: Kiro generates requirements documents in EARS format, including an introduction, requirement items, and user stories. EARS (Easy Approach to Requirements Syntax) was proposed by Alistair Mavin and colleagues in 2009 during a Rolls-Royce aerospace project, designed to address the ambiguity and vagueness of natural language requirements. EARS defines five categories of requirement templates: Ubiquitous, Event-Driven, State-Driven, Optional, and Unwanted Behaviour — each with a fixed sentence structure. In AI-assisted programming, the value of EARS format lies in its sufficient structure to be precisely parsed by language models, reducing implementation deviation caused by natural language ambiguity. The system also proactively asks clarifying questions before generating, and you can use the newly added "quick plan mode" to generate all documents in one shot based on a Q&A session.

Design Phase: Generates higher-level design documents containing Mermaid diagrams, ASCII architecture diagrams, sequence diagrams, and more. Erik emphasizes: this is the moment to pause and intervene manually — bring your own knowledge, experience, and judgment to update the document, because the quality of AI's output depends directly on the quality of what you feed it.

Implementation Phase: Generates a step-by-step task list. One standout feature: Kiro generates property-based tests. This is a testing paradigm pioneered by the QuickCheck library (1999) in the Haskell ecosystem. The core idea is: rather than specifying concrete input/output examples, you describe "properties" (invariants) that the code should satisfy, then the framework automatically generates large numbers of random inputs to verify whether those properties hold. Compared to traditional example-based testing, property testing is more effective at uncovering edge cases and unexpected behaviors. In the JavaScript/TypeScript ecosystem, Kiro uses the FastCheck framework for this, running dozens or hundreds of iterations with different values to verify that requirements are correctly satisfied. In the context of AI-generated code, property testing is especially valuable — it systematically verifies whether the AI's understanding of requirement specifications is accurate, rather than just validating a few manually constructed cases. Erik strongly recommends enabling this feature.

He also shared a practical tip: once the task list is generated, ask AI to "move the first four tasks to the top and build an MVP first" — this lets you see working results quickly, then implement the full feature set incrementally.

The Value of MCP: Connecting Real Project Management Data

Erik also discussed the Model Context Protocol (MCP). Addressing skepticism about whether MCP is already obsolete, he believes MCP is still maturing with a long road ahead, and that its security capabilities in particular deserve continued attention.

The Model Context Protocol (MCP) was open-sourced by Anthropic in November 2024. It's a standardized open protocol defining the interaction interface between AI models and external data sources and tools. Its design goal is analogous to USB-C in the hardware world — eliminating fragmented integration costs through a unified protocol. MCP uses a client-server architecture: AI assistants act as MCP clients, and various data services (Jira, GitHub, databases, etc.) expose their capabilities as MCP Servers. There are now hundreds of community-maintained MCP Servers covering mainstream development tools and SaaS platforms. In discussions of MCP's maturity, security issues — such as prompt injection attacks delivered through malicious MCP Servers — are a key focus in the industry, which is precisely what Erik means by "security capabilities deserve continued attention."

The core scenario he values for MCP is: pulling tickets and large requirements documents from Jira, Asana, and similar tools into the Spec-Driven Development workflow. This means if a product manager has already written requirements documentation, you can use it directly as an input source for spec generation, making the entire process more aligned with real team collaboration. You can also add rules to steering docs telling AI which MCP server to fetch information from.

Closing Thoughts: Specs Aren't Just for Greenfield Projects

A common misconception is that Spec-Driven Development only works for brand-new projects built from scratch. Erik explicitly pushes back: he's seen legacy applications that have been running for years with dozens or hundreds of spec files inside. This approach is especially well-suited for deep features requiring upfront planning, complex projects, and structured delivery. Kiro has even added spec mode for bug fixes (though for small changes, writing code directly is probably more cost-effective).

Ultimately, the value of Spec-Driven Development isn't just about being "faster" — it's about introducing necessary discipline and human judgment into the AI-assisted programming process to produce higher quality code. In a world where AI interns are becoming increasingly capable and increasingly prone to going off-script, that discipline may matter more than any individual tool.

Key Takeaways