Paperwork sucks. So does filling out forms. They represent drag and process. If only we could just stare into a product manager’s eyes and transmit our wants and needs in 8K detail. 

Alas, we can’t do that—so we have to ask questions. Good product managers ask a ton of questions. Great product managers not only ask lots of questions, but ask the right ones, and fill in the gaps with every bit of detail. 

I’ve been involved in software development for what feels like hundreds of years now, and for most of that time, the artifact that’s launched a million missions has been the spec, also known as a PRD (product requirements document) or funcSpec (functional specification). It is, for lack of a better word, an agreement. It’s not legally binding, but it does the thing that heads off so many awkward and sometimes terrible conversations: It sets expectations. 

Fast forward to today, and we’d still love to stare into that product manager’s eyes (and not open up Microsoft Word). But now, AI—and especially vibe coding—is here. Finally, we can type in three sentences and get what we need. No more specs! 

But missed expectations with humans can be sorted out; missed expectations with machines leads to an unmitigated sloppy mess. Why? It’s not because the machines aren’t smart—and they’re getting even smarter. The thing about AI is it will rarely ask you to clarify and fill in the gaps. Instead, it’ll just go to town, unfurling all sorts of code and grabbing JavaScript libraries like a hungry vacationer rampaging an all-you-can-eat buffet. 

I’m fully confident that AI companies will sort out the bugs down the road. But bugs are only half the picture. An LLM’s output can work perfectly—but still not be what you wanted. In fact, how can it be what you wanted? You never told it what you wanted beyond a few sentences. AI has no notion of gap analysis. It’s not worried about its job if it ships the wrong thing. It just wants to ship.

And yet, it still can’t seem to ship anyway. Even if it filled in all that ambiguity with AI packing peanuts, the software often doesn’t work. Many vibe-coding tools take the wheel and start fixing their own bugs within seconds of showing you software. It’s a brutal right hook and uppercut: It doesn’t know what you want, and even with its own assumptions, it can’t finish the job reliably. 

Spec time! 

OK, so vibes are great, but computers can’t just catch your vibes. You’re going to need to find some time to meet in a calm, quiet place and talk it out. Fortunately for us, computers—even computers equipped with AI smarts—will patiently listen. It’s on us to guide through all the glorious details. “Bring a yellow pad and let’s walk through it”: It’s spec time. 

Github calls it Specification-Driven Development, or SDD. They’re acknowledging that specs are not a nice-to-have, but rather a key part of shipping good, solid software reliably. Amazon’s Kiro also embraces this SDD approach. 

Github sums it up nicely:

This transformation is now possible because AI can understand and implement complex specifications, and create detailed implementation plans. But raw AI generation without structure produces chaos. SDD provides that structure through specifications and subsequent implementation plans that are precise, complete, and unambiguous enough to generate working systems. The specification becomes the primary artifact. Code becomes its expression (as an implementation from the implementation plan) in a particular language and framework.

Nice progress! Code, especially large amounts of it, can’t be poured into a cake pan and baked. It doesn’t work. Structure is the operative word there. By segmenting the work and narrowing the opportunity for digression, you’re limiting AI’s tendency to go astray. Sort of. There are still many challenges and it comes down to how AI codes.

We should constantly remind ourselves that AI doesn’t think holistically—it doesn’t think at all. It is notoriously short-sighted. It may look like it’s turning needs and requirements into code, it isn’t: It’s just copying, as best it can, the closest approximation of an artifact it thinks will fit the bill. It favors form over function. In fact, it is all form. And code—really good code—comes from an intimate understanding of the needs codified in that spec. 

Spec is better, no doubt. The jazz guitarist is waiting his turn. He gets the structure and likes how you’ve set him up. But it’s solo time, and he’s gonna share his expression (to quote Github) of what he thinks is just the coolest three minutes of jazz guitar. The spec, as far as he’s concerned, was a rough sketch. He’ll take it from here. 

It’s futile to declare defeat with AI. It’s getting better—and we humans are getting really good at manipulating it to do a better job. SDD is an excellent step forward. Lord knows 22 unpunctuated words in a prompt box aren’t gonna cut it. But there’s still so much to do. We’ll check back in 6 months. Maybe I can finally use my prog rock analogy then.