Your Spec Driven Workflow Is Just Waterfall With Extra Steps

AI coding tools were supposed to change everything. And they did! But maybe just not how we expected. The first wave was chaos. Vibe coding. Let the AI write whatever it wants and hope for the best. It worked well for prototypes, but fell apart for anything real.

So the community course-corrected. The answer was structure in form of Spec-driven development. Generate requirements, then a design doc, then a task list, then let the agent execute. Tools like Kiro and spec-kit promised to keep agents on track with meticulous planning.

It sounded smart. It felt responsible. And it's a trap.

François Zaninotto recently called this what it is: waterfall striking back. His team tested these tools and found themselves generating 1,300 lines of Markdown just to display a date. The specs were verbose and the agents ignored them anyway. Developers spent more time reading than thinking.

We've reinvented Big Design Up Front. We just replaced Word documents with Markdown and project managers with LLMs.

I tried it and I wanted to believe. But I think I found a better way.

The Problem With Spec-Driven Development

For every change, you review the spec to see if it makes sense. Then you review the code to see if it matches. That's double the work.

And the moment you deviate, the spec drifts. You find a better approach, hit an unexpected edge case, and suddenly you're maintaining documentation that no longer reflects reality. We've been here before. It was called waterfall.

But here's what bothers me most: the ratio is backwards. We're spending more time reading AI-generated prose than actually thinking. I find that deeply problematic. I'm still struggling with this myself. It's easy to let the AI do the thinking for you. That's why I started doing Manual Mondays: one day a week with all AI tools switched off, just to keep my software engineering brain from rotting.

Maybe you've had better luck with it? Idk.

What I Actually Wanted

• I wanted AI that augments my thinking, not replaces it with bureaucracy. Something that helps me reason through problems, not generate documents I'll never read twice.
• I wanted structure without artifact sprawl. A way to stay organized without drowning in Markdown files that go stale the moment I commit.
• I wanted tests as the specification. Executable, not prose. Something that lives in the codebase, runs in CI, and tells me immediately when things break.
• And I wanted to stay in flow. Stay in the editor. No context switching between chat windows, terminals, and documentation wikis. Just me, the code, and an AI that keeps up.

That's when I found it, a more structured way.

My Workflow: Three Commands

They're simple, but they changed how I work with AI completely!

/reason — Think before you code

This forces the AI to analyze the problem before writing a single line. Instead of jumping straight to implementation, it maps out the approach, surfaces edge cases, and spots potential pitfalls.

The difference is night and day. Without it, I'd often get halfway through a generated solution before realizing the approach was wrong. Now I catch bad directions before I've invested any time. Thinking first sounds obvious. But when the AI is eager to write code, you have to force the pause. It's like a dog that you have to keep in leech

/question — Enrich the context

This generates three targeted questions about the task. I answer them, and suddenly the AI is working with my context, not generic assumptions.

The AI doesn't know your codebase conventions. It doesn't know why you made that weird architectural choice six months ago. It doesn't know what your team tried last sprint that failed. But you do. This command extracts that knowledge and puts it to work. The first-pass output improves dramatically.

/tdd — Tests as the spec

This writes failing tests first, then implements until they pass. The specification becomes executable code that lives in your repo.

No drift. No stale documentation. No wondering if the spec still reflects reality. The tests are the spec, and they run every time you push. If something breaks, you know immediately. This is the core of my workflow. Everything else supports it.

At Queenslab we teach the exact prompts behind /reason, /question, and /tdd along with the full workflow. If you want to stop wrestling with AI agents and start shipping or want more useful tips for AI-driven development, join in a free webinar

Why This Beats Agents and Spec Files

• No context switching since everything happens inside Cursor. I'm not jumping between a chat window, a terminal, and a folder full of Markdown files. The conversation happens where the code lives.
• No files to maintain. The conversation is ephemeral. The tests persist. I don't have a specs folder that grows stale and becomes a graveyard of good intentions. The only artifact that matters is the code and the tests that verify it.
• You stay in control. The AI assists your thinking. It doesn't replace it. I'm still the one deciding what to build and why. The AI helps me think it through, surfaces what I'm missing, and writes code I can verify immediately.
• It scales to existing codebases. This is where spec-driven development falls apart. You can't generate a project-wide spec for a codebase that's been evolving for three years. But you can have a conversation about the next change. You can write a test for the next feature.
  
  My workflow doesn't care how big the project is.

The Senior Engineer's Take

I've been writing software long enough to know what I'm doing. I don't need an AI that over-explains and I don't need guardrails that assume I'll wander off a cliff without a 50-page spec holding my hand.

The best AI workflow is the one that matches how you already think. For me, that's reasoning through a problem, asking the right questions, and writing tests before code. Cursor lets me encode that into three main commands.

Spec-driven development assumes you can't be trusted. That without extensive documentation, you'll lose the plot. I disagree simply because I trust myself. I just want a tool that helps me think faster. A framework that augments me as an engineer.

Further reading: François Zaninotto's Spec-Driven Development: The Waterfall Strikes Back goes deeper on why SDD fails in practice.