In some circles vibe coding is all the rage right now. (In fact my colleague Kate Holterhoff declared this to be “hot vibe code summer).”

Why the appeal? As I discussed in a previous post, AI-powered development tools are well-suited for helping both developers and adjacent personas (like PMs and designers) with informal, rapid prototyping. Rather than waiting for scarce development cycles, people can experiment with ideas in higher fidelity than traditional methods (like design docs, wire framing, white boarding, etc) allow.

Most current vibe coding tools are great for early stage exploration but can fall short when generating code suitable for production-scale systems. Generally speaking these are not tools for betting your business on, or even business applications. (At least not yet.) There are legitimate concerns about whether vibe coding creates more liabilities than benefits.

Perhaps vibe coding can scaffold code quickly or spin up small projects, but at scale it tends to:

• Not build code efficiently. If you want neat, maintainable, reusable code, vibe coding probably ain’t it.
• Be quite tricky to debug.
• Create performance problems. Remember the anecdote about the database getting hammered by select * queries written via vibe coding? (I hope you do because I can’t find it again; all my “vibe coding database performance impact” searches are just turning up the Replit debacle)
• Have unreliable behaviors, sometimes catastrophically so (see the Replit database deletion debacle)
• Shift the bottlenecks of creating software to debugging, testing, and deployment pipelines.

There’s a chasm to cross from magical prototypes to maintainable, deployable systems.

Spec-driven development has emerged as a potential response to this gap.

(there are going to be glasses in this post. #sorry #notsorry)

Spec-Driven Development 🕶️

‘Spec’ in this case stands for specification, an artifact that captures requirements before writing any code. Rather than relying exclusively on a series of prompts, the user augments the AI’s context with a more structured approach.

“I’m sure you’ve been there: prompt, prompt, prompt, and you have a working application. It’s fun and feels like magic. But getting it to production requires more.”
– Nikhil Swaminathan and Deepak Singh

This is not to say no prompting occurs. Users still interact with AI via chat.

Let’s Zoom In: A Simple Comparison 🔭

The below prompt is not necessarily how I suggest either vibe coding or doing spec-driven development if you want to use your tokens efficiently, but rather is an attempt to illustrate how the approaches differ if I were building a simple greenfield personal website. The below screenshots are from Kiro, an agentic IDE from AWS that allows users to build either using Vibe Mode or Spec Mode.

Vibe Coding

Prompt:

I want to build a personal website to showcase my work portfolio. I want to import articles I've written via an RSS feed.

The AI responds with suggestions for which tech stack to build on, questions about where to host, and then starts scaffolding it out. It jumps straight to writing code.

Spec-Driven Development

In spec-driven development I could use the exact same prompt, but instead of diving into code the system first creates markdown documents focused on user stories and design.

(This is a truncated screenshot. The system actually generated 4 requirements based on this simple request.)

The user can then go in and edit this markdown. Requirements can be added, removed, and amended. Additional context of what’s being built is captured not just in the ephemerality of prompts alone but in a living document.

Kiro

As stated, the above example utilizes AWS’ recently released Kiro, an agentic IDE that allows users to build with multiple modalities: either vibe- or spec-based development.

There are many tools on the market that enable vibe coding, but spec-driven tools are newer to the scene. Kiro is currently leading the charge in terms of attention and adoption in the latter space.

When using spec-based development, Kiro allows users create their requirements; from there the agents create an editable design document, and then a task list of things to do to build the code according to the specifications.

In addition to specs, Kiro contains concepts like ‘steering’ (essentially rules that agents will follow before responding) and ‘agent hooks’ (things you can offload from the spec to help keep the context window from getting too large; for example you can create an agent hook that runs a unit test every time you commit an update.)

VS Code users will feel comfortable with the UI, and the release blog says “’Kiro is built on Code OSS, so you can keep your VS Code settings and Open VSX compatible plugins.’”

Apart from the tech itself, the branding of the product is another notable aspect of Kiro. Per my colleague James Governor:

Intriguingly Kiro isn’t branded AWS or even Amazon, it stands alone – it is simply Kiro. Amazon is going to markedly increase velocity in building its AI dev tools. Kiro: watch this space.

Speculation vs. Specification 🧐

In her book Speculation and the Darwinian Method, my colleague Kate Holterhoff explores the definition of ‘speculative’ as “a way of thinking that involves abstract reasoning.”

At its core, vibe coding is speculative software development: fast, fluid, and exploratory. You’re reasoning abstractly about what might work and letting AI tools help play out that line of thinking in code. It’s improvisational. It’s playful. It’s powerful, but it’s not always production ready.

Spec-driven development enters the market as a more structured approach. It’s a methodology that prioritizes intentionality and alignment.

Both approaches have their place, but vibe coding de facto favors the lone developer. We frequently talk about the AI tools serving as a paired programmer for the developer; the collaboration point is between the AI code assistant and the builder. If another team member wanted to pick up the project, they can possibly try to read through the chat history but most likely are just going to have to dive into the source code.

Spec-driven development, on the other hand, creates human-readable artifacts that share a project’s design and intent. It captures more than what is commented in the code; they start to document the ‘why’ behind what was built, not just the ‘how.’ This widens the points of collaboration beyond just ‘dev + AI’, and makes it simpler if anyone else needs to pick up the project.

Maintainability and understandability are crucial for enterprise-grade software. There is an inherent level of unmaintainability in vibe coding, and there is potential for greater maintainability with spec-driven assets. This is arguably the best argument for enduring the front-loaded effort of creating a spec as compared to diving straight into the project. It remains to be seen if spec-driven code is production ready at scale, but its methodology is inherently more aligned to the needs and expectations of enterprise software development.

Specs: The Lens of Intent 🔎

I’ve heard several articulations that “the spec is the source of truth” and I’m not sure I agree with that framing. At least not yet.

To date, a challenge with all code (whether authored by humans or LLMs) is capturing the authors’ intent. How do we communicate to our colleagues (both current and future) what problems our code is attempting to solve?

Generally speaking as software engineers, we have a cultural deficit in explaining our own history to each other. We attempt to fill the gap with code comments and code reviews, but often we are left with oral history. (See Bryan Cantrill’s excellent talk on the subject.) Now specs are an attempt to capture that intention as well, now in an AI-driven development environment that historically has been devoid of this.

While that all can provide crucial informational context, in a pre-AI age I don’t think we’d ever call any of those things “the source of truth.” The source of truth is what builds. The source of truth is the code.

AI vendors have a north star where natural language supersedes the code itself, and in this vision specs could conceivably become the source of truth. But the industry is far from being there in terms of functionality and reliability.

So I push back on the framing that specs are the source of truth. I feel much more comfortable calling them the source of intention.

New Frames, Same Vision 👓

Vibe coding and spec-driven development aren’t opposing camps. They’re different tools for different stages of the creative process. Vibe coding unlocks momentum. It’s the spark. It’s how you get unstuck, test an idea, or just get something working without waiting for a meeting or a milestone. But the magic of prototyping doesn’t always translate into the rigor of production.

Spec-driven development helps teams slow down just enough to think clearly about what they’re building and why. Specs aren’t (yet) the canonical source of truth, but they do something arguably just as important: they clarify intention, capture context, and create artifacts that outlive the memory of the developer (or the AI’s token window.)

In a world where AI is reshaping how we build software, vibe coding vs. spec-driven development is not an either/or but a yes and. That said, specs are a new interesting and important development in how we’re building.

---

Related Research:

• AI Engineers and the Hot Vibe Code Summer
• Vibe Coding is for PMs
• Giants awaken. Google Cloud GeminiCLI, AWS Kiro, developer experience and the need to ship and keep shipping

Disclaimer: AWS is a RedMonk client. This post is not compensated and reflects my own opinions.

Image credit: Glasses frames licensed from Adobe stock.