DEV Community

Cover image for Spec-Driven Development: The New Waterfall, and It's a Good Thing
Tomasz Jędrzejewski
Tomasz Jędrzejewski

Posted on

Spec-Driven Development: The New Waterfall, and It's a Good Thing

Brings back discarded documentation habits

It's been almost a year now since I stepped into the world of agentic coding and Spec-Driven Development. Before, I really hated it, because the quality of LLM-s was poor. I spent more time fixing the generated code than I saved on letting the agent write it. But this has changed. Writing specifications, refining them with the agents, validation against rules, system design and existing requirements - it became new routine in my projects.

Agentic coding did not increase my speed in many places, but instead shifted the effort from writing code to the discovery and design phase. And there are some new extra benefits of it: things that previously happened in my head, are now documented. There are written artifacts: specifications, decision logs, architecture documentations, that previously we often did not have time to write.

I have recently read a great article of Sylwia Laskowska on this topic: Is Coding with AI Actually Faster and Cheaper? I shared the thoughts above in the comments, and then I realized one thing: all that I do with the agents resembles me the long-gone software development methodology: The Waterfall Model.

What's Waterfall?

The Waterfall Model in software development fell out of use many years ago, replaced with various agile methodologies. For those of you, who hadn't got a chance to work with it, here's a quick overview, what it is. It's the first software development model with the origins traced back to 1950s (presentation of Herbert D. Benington). It assumes developing the software into several sequential phases:

Waterfall phases: Requirement Analysis, System Design, Implementation, Testing & Integration, Acceptance & Deployment, Maintenance

The key feature is that you advance to the next phase only when you successfully complete, review and approve the current one.

The intent behind Waterfall Model was clearly good: capturing the issue in the early phases was cheaper than fixing the bug in the finished product. In theory, the extra time spent on requirement analysis should later pay off later, right? Right?!

Rightn't. Left. Whatever. The Waterfall Model missed one point about software development: usually, you don't actually know your requirements upfront. You don't even know what you're going to build. You keep learning the project, experimenting by trial-and-error, refining your understanding of the needs. The Waterfall phases are long: they can last weeks and months. The feedback loop is so long that you learn about a flawed initial assumption many months later. The Waterfall Model could only work in a narrow niche of well-explored, mature domains with the access to Subject Matter Experts who know customer needs.

Spec-Driven Development

I looked at how I work with the agents in the Spec-Driven Development:

SDD Phases: Creating Specification, Creating Technical Plan, Breaking into Tasks, Implementation, Testing & Integration, Acceptance & Deployment

It's quite amazing, how this flow translates into Good, Old Waterfall Model:

  • Specification corresponds to the Requirement Analysis
  • Technical Plan corresponds to the System Design
  • Breaking into tasks was usually also present in Waterfall, just not named explicitly
  • In both, we produce structured, detailed documentation artifacts.
  • Implementation, Testing, Acceptance - in these phases, we strictly follow the specifications and plans created earlier.

But most of all: we move to the next phase only when we successfully complete the current one. You can say anything, but SDD is the Waterfall Model, just with slighlty different names and added AI :).

Why It Actually Works Now?

Is this analogy a bad thing? Let's look at what we just said earlier: the problem with the Waterfall Model is the long feedback loop. Combined with unclear requirements (a normal thing in IT), we get a disastrous combination. But Spec-Driven Development removes this factor from the equation:

  • Individual phases take minutes and hours, not weeks and months.
  • AI can quickly rework large amount of paperwork, if we change our minds about the direction.
  • AI can quickly translate rough descriptions of intents into structured documents and plans.
  • AI can quickly validate the consistency of the requirements and plans.

A single developer can now complete the full SDD cycle within hours. Morever, when cycles are so short, we don't need to design the entire system in one shot. We can iterate on smaller increments with the granularity that suits us. If the outcome does not satisfy us, we can easily revert to the earlier phase or even throw the entire cycle away. This is a game-changer.

Documentation: Revived Benefit

One thing that the Waterfall Model did right was the documentation, because writing it was a part of the process. It needed detailed documentation, so that programmers knew what to write - their role was "just" translating the specification into the code. Guess what - this is exactly what we expect from the coding agent in SDD.

In my opinion, agile methodologies never managed to get the documentation right. Developers could write the documentation only if additional factors forced them:

  • The customer required it (no documentation = no customer = no money = you starve and die, pretty good motivator).
  • Developers overwhelmed with support tickets: we write documentation to stop people asking the same basic questions thousands of times.

Otherwise, the projects rarely had even a basic README. We had to accept that in all-human development, certain things take time and all we could do is to pick our poison. Spec-Driven Development as a revived Waterfall Model brings the documentation back to the game, because it's cheap now, and we need it to drive the agents.

AI Development Speed

"Did AI speed you up?"

"No, I started doing Waterfall."

In the introduction, I said that AI did not necessarily speed me up, but rather helped me shift the effort to the discovery & design. The way how I do it is basically Waterfall Model but an order of magnitude faster. Because of that, it actually works.

So I think it's fair to say the following and wait for reactions: "No, AI did not make me faster. It made me entering into the Waterfall Model." :)

Conclusion

In the IT and engineering, things are rarely black and white. We have consequences, trade-offs and circumstances. Our role is to rate them and tell, which ones are relevant to us in the given project. An idea that did not work in the past, may work now after changing the circumstances. I think this is what is happening to the Waterfall Model. AI removed the problematic factor, and the good parts emerged again as Spec-Driven Development.

Can this conclusion change our lifes?

  • If I were just interested in finishing a feature and moving on to the next one - probably not.
  • But I want to understand why certain things (don't) work. Maybe I won't see the benefits now, but I believe that every such discovery may pay off later.

The why factor helps me make better project decisions... and explain them to the stakeholders. That's what they pay me for, and I think - that's what you should prepare for, as you are less and less engaged in pure coding.

Top comments (6)

Collapse
 
kenwalger profile image
Ken W Alger •

I like the Waterfall comparison, particularly the observation that AI hasn't necessarily made development faster so much as shifted the effort toward discovery, specification, and design. That's been consistent with my own experience.

One distinction I'd make, though, is that shortening the feedback loop doesn't necessarily solve the original requirements problem. It makes discovering that we were wrong considerably less expensive.

I've been experimenting with spec-driven development alongside independent verification of AI-generated software, and one recurring challenge is that the specification itself can be internally consistent while still missing an important behavioral contract. An agent can faithfully implement what we wrote without implementing what we actually needed.

That's where I think the iterative aspect becomes especially important. Implementation and verification aren't just downstream activities that confirm the specification. They're also opportunities to discover requirements we didn't know were missing.

Perhaps what we're getting isn't quite Waterfall returning, but something closer to very short Waterfall cycles where each pass can revise the requirements themselves.

And I agree about the documentation benefit. Having the assumptions, decisions, and contracts written down is valuable even when the code turns out to be wrong. At least we have something concrete to examine and correct rather than trying to reconstruct what everyone thought they meant. :)

Collapse
 
paullovelace profile image
Paul Lovelace •

The "did AI speed you up? No, I started doing Waterfall" exchange is the whole piece in two lines. The part I keep turning over is the documentation one — SDD brings the docs back because they're cheap now, but the spec itself can go stale just like code did, and then the agent faithfully implements the wrong thing faster. Do you re-run the spec past the agent when requirements change, or does the spec become the new thing you maintain by hand?

Collapse
 
iictp profile image
IICTP •

That stale-spec worry is exactly the one I keep coming back to as well — a spec the agent trusts completely becomes a single point of failure if nobody re-validates it when requirements move. The part of the article that gives me some comfort is the short feedback loop: phases take minutes, so re-running the spec past the agent after a change is cheap enough to actually do. I wonder whether teams end up treating the spec as the thing that gets reviewed in the PR, rather than the code — has that been your experience?

Collapse
 
zyxist profile image
Tomasz Jędrzejewski •

That's a very good point, and IMHO a topic worth further exploration on its own. My observations:

  1. Anything that is a source of truth is vulnerable to the staleness problem: be this the code, the documentation, the spec, the dataset... if we ever invent a completely novel source of truth about the software that would replace specs, code and everything - the staleness question will emerge there naturally, too. The mere fact that it occurs is just an observation of the natural process.
  2. What we can do is finding techniques specific to the given source of truth that help minimize the problem and bring it to the manageable level.
  3. The efficiency of those techniques is something we should assess, when deciding about what our source of truth should be.

Currently, I observe that we are in the phase of exploration what works, and what does not work for SDD, when managing large specs over long periods of time. The observation window is still very short, but as the time goes by, we should collect more and more "lessons learned".

Thread Thread
 
iictp profile image
IICTP •

That's a useful reframing — treating staleness as a property of any source of truth rather than a spec-specific flaw makes the question much more tractable. The per-source-technique angle is the part I'd want to dig into: a spec at least has the advantage that drift can be reviewed as a diff, unlike a dataset quietly going stale. Of the techniques you've seen so far for keeping large specs fresh over long projects, is there one you'd bet on first, or is it still too early to call?

Collapse
 
kursatyz profile image
Kürşat Yılmaz •

Spec-driven workflows shift the failure mode from runtime drift to contract staleness, because once an agent generates code against an underspecified memory ceiling or retry boundary, regenerating from a tightened spec is far cheaper than tracing synthetic state machines. Prompting guesses; specs enforce invariants.