Don't Go Chasing Waterfalls

A few months ago, I was introduced to spec-driven development with AI and Kiro. While I didn’t continue using Kiro, I kept using the technique because it helped guard against the challenges of working with AI at the time. I’d spend time building out a detailed spec requirements, edge cases, acceptance criteria; hand it to the model, and watch it produce something technically faithful to the document but somehow still wrong.

So I’d refine the spec. Add more detail. Go back and forth. Recently, I realized this is waterfall development on a tighter loop. I’d just rebuilt the waterfall inside my AI workflow without realizing it.

The Spec Problem

Spec-driven development felt like the better way to work with AI. You think everything through upfront, write it down precisely, and let the model execute. It seemed more rigorous than just winging it with prompts.

But the spec creates a false ceiling. You’re front-loading all your thinking into a document that has to be correct before anything moves. The longer the spec, the more surface area for something to be subtly off. Instead of a short feedback loop, you’ve got a long one disguised as planning.

The worst part is that reading back through a spec to check it is its own cognitive tax. You’re not building anything; you’re auditing a document you or AI wrote.

What Actually Works Better

As the models have improved, I’ve found that precise articulation in the moment beats upfront specification. Not vague, but precise ones. There’s a difference. For example, a vague prompt like “Make this code faster” leaves the model guessing your intentions and priorities. In contrast, a precise prompt would be “Optimize this function to reduce its time complexity from O(n^2) to O(n), while keeping the output the same.” The latter is clear about what you want and why, which leads to much better results.

The format that best maps to how current models process intent is one most developers have encountered but rarely taken seriously: the user story.

As a [person], I want to [do something], so that [outcome].

It sounds almost insultingly simple. But that structure, actor, action, purpose is narrative. And narrative is the native format of language models. When you write in that shape, you’re not just describing a feature; you’re giving the model a perspective from which to reason.

Developers Aren’t Always Users

Here’s the uncomfortable part. A lot of developers are bad at this. Not because they can’t write, but because they’ve never had to inhabit the user’s perspective. You can be an excellent engineer and have very little intuition for how someone else experiences the thing you build.

Open source software is the most honest illustration of this. There are open-source projects that are technically extraordinary but practically unusable for anyone who didn’t build them. Commercial alternatives with a fraction of the technical depth dominate because someone on the team was thinking about the person on the other end.

That’s not a coding skills gap. It’s an empathy gap. And AI coding tools won’t cover for it, they’ll actually expose it faster.

Who This Shift Favors

If precise, user-centric articulation is now a core part of writing software, then product people have a significant natural advantage. They spend their days thinking about users, writing in a narrative style, and translating needs into requirements. That’s the exact muscle this demands.

This doesn’t make developers obsolete. The technical judgment about architecture, tradeoffs, and when the AI is confidently wrong still matters enormously. But the entry point to building is shifting. The person who can describe what a user actually needs, clearly and precisely, is more valuable in an AI-assisted workflow than they’ve ever been before. The good news is that developers can adapt to this shift. Building user-centric skills is a learnable process, whether through working alongside product people, practicing user story writing, or seeking direct feedback from real users. Collaborating more closely across roles makes teams stronger, and developers who embrace this perspective will be even more effective in an AI-first world.

The question for developers is whether that’s a threat or an invitation to grow.

The Practical Shift

If I were to distill this into something actionable:

Stop thinking about what the system should do and start thinking about who is using it and why. Write that down first. Let the spec emerge from building rather than precede it.

The feedback loop gets shorter. The output gets closer to what you actually wanted. And you spend less time auditing documents and more time making decisions.

That, it turns out, is what agile was always supposed to feel like.