Spec-Driven Development: The Waterfall Strikes Back

By François Zaninotto November 12, 2025 • 7 min read

Spec-Driven Development (SDD) revives the age-old concept of extensive documentation preceding coding—a clear echo of the Waterfall era. While it purports to offer structure for AI-driven programming, it carries the significant risk of stifling agility under cumbersome layers of Markdown. This post delves into why an iterative, natural-language approach might be a superior fit for contemporary software development.

The Rise of Specification

Coding assistants, with their minimalist chat interfaces replacing familiar IDE menus and buttons, can be intimidating. The question arises: how can we guarantee code correctness with such limited guidance?

To address this, the open-source community has devised an ingenious method to guide coding agents. Starting with an initial prompt and a few instructions, a Large Language Model (LLM) generates comprehensive product specifications, an implementation plan, and a detailed list of tasks. Each subsequent document builds upon the previous one, allowing users to refine specifications through edits.

Ultimately, these documents are passed to a coding agent (such as Claude Code, Cursor, or Copilot). The agent, now properly guided, is expected to produce robust code that fulfills the business requirements.

This methodology is known as Spec-Driven Development (SDD), and several toolkits are available to facilitate its adoption. Notable examples include:

• Spec-Kit by GitHub
• Kiro by AWS
• Tessl by Tessl
• BMad Method (BMM) by BMad Code

For a thorough comparison of these tools, I highly recommend Birgitta Böckeler's excellent article: "Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl."

The Markdown Awakens

So, what does a specification look like in practice? Essentially, it’s a collection of Markdown files. Consider this example using GitHub’s spec-kit, where a developer aimed to display the current date in a time-tracking application. The result was 8 files and 1,300 lines of text:

Here's another example from Kiro for a minor feature (adding a “referred by” field to contacts in Atomic CRM):

• Requirements.md
• Design.md
• Tasks.md

While these documents appear relevant at first glance, the devil lies in the details. Upon practical application of SDD, several shortcomings become apparent:

• Context Blindness: Similar to coding agents, SDD agents primarily derive context through text searches and file navigation. They frequently overlook existing functions that require updates, necessitating reviews by both functional and technical experts.
• Markdown Madness: SDD generates an excessive volume of text, particularly during the design phase. Developers find themselves spending a disproportionate amount of time poring over lengthy Markdown files, searching for fundamental errors buried within overly verbose, jargon-laden prose. This process is inherently exhausting.
• Systematic Bureaucracy: The prescribed three-step design process often proves excessive for most scenarios. Specifications frequently contain redundancies, hypothetical edge cases, and unwarranted refinements, giving the impression of documentation crafted by an overly meticulous clerk.
• Faux Agile: SDD toolkits often produce what they label as “User Stories,” yet they frequently misapply the term (e.g., “As a system administrator, I want the referred by relationship to be stored in the database” is not a true user story). While this doesn’t cause bugs, it is distracting.
• Double Code Review: The technical specification itself often includes code. Developers must review this pre-generated code before execution. Since bugs will inevitably arise, they must also review the final implementation. Consequently, review time effectively doubles.
• False Sense of Security: The SDD methodology aims to keep the coding agent on track, but in reality, agents don't consistently adhere to the specification. In the aforementioned example, the agent marked the “verify implementation” task as complete without writing a single unit test, opting instead for manual testing instructions.
• Diminishing Returns: SDD excels when initiating a new project from scratch. However, as an application grows, the specifications often become less relevant and impede development speed. For large, existing codebases, SDD is largely unfeasible.

Most coding agents already possess a plan mode and a task list, making SDD’s added benefits often negligible. In some instances, it even increases the cost of feature development.

To be fair, SDD can help agents maintain focus and occasionally identify edge cases that developers might miss. Nevertheless, the trade-off—spending 80% of your time reading rather than thinking—is, in my opinion, not worthwhile.

Revenge of the Project Manager

Perhaps SDD’s current limitations stem from the immaturity of its toolkits and the need for prompt refinement. If this is the case, improvements might be just a few months away.

However, my personal conviction is that SDD represents a misguided direction. It attempts to solve a fundamentally flawed problem: “How do we remove developers from software development?” It seeks to achieve this by replacing developers with coding agents and enforcing meticulous planning to control those agents.

In this respect, SDD strongly recalls the Waterfall model, which mandated extensive documentation before any coding began, effectively reducing developers to mere translators of specifications into code.

Yet, developers have long transcended the role of simple executors, and the Big Design Up Front approach has consistently failed, primarily because it relies on an accumulating stack of unverified hypotheses.

Software development is fundamentally a non-deterministic process, meaning planning alone cannot eliminate uncertainty (as famously articulated in the classic No Silver Bullet paper).

Moreover, who is SDD truly designed for? One must possess the expertise of a business analyst to detect errors during the requirements phase and the skills of a developer to identify issues during design. Consequently, it fails to solve its purported problem (removing developers) and can only be effectively utilized by the rare individuals who master both domains. SDD repeats the same error as No Code tools, which promise a “no developer” experience but invariably require developers to implement and maintain them.

A New Hope

Agile methodologies successfully addressed the challenge of non-deterministic development by prioritizing adaptability over strict predictability. I believe they illuminate a path where coding agents can genuinely assist us in building reliable software without drowning in Markdown.

Provide a coding agent with a sufficiently simple problem, and it will likely stay on track. Instead of attempting to translate complex requirements into equally complex design documents, we should break down complex requirements into multiple simpler ones.

I have successfully used coding agents to build fairly intricate software without ever directly manipulating the code, by adhering to a straightforward approach inspired by the Lean Startup methodology:

1. Identify the next most critical risky assumption in the product.
2. Design the simplest experiment to test it.
3. Develop that experiment. If it fails, return to step #2. Otherwise, repeat from step #1.

As an example, consider this 3D sculpting tool with adaptive mesh, which I developed with Claude Code in approximately 10 hours:

(Your browser does not support the video tag. This section originally contained an embedded video demonstration.)

I did not write any spec. I simply added small features incrementally, correcting the software when the agent misunderstood my instructions or when my initial ideas proved ineffective. My instructions, visible in the coding session logs, were often concise and sometimes vague, leading occasionally to dead ends—but this is acceptable. When implementing simple ideas is cost-effective, building in small increments becomes the fastest route to a robust product.

Agile methodologies liberated us from the bureaucracy of Waterfall. They demonstrated that close collaboration between product managers and developers negates the need for extensive design documents.

Coding agents supercharge Agile because they allow us to literally articulate the product backlog and witness its construction in real-time, eliminating the need for mockups!

This approach, however, has one drawback compared to Spec-Driven Development: it lacks a formal name. While “Vibe coding” sounds dismissive, let's refer to it as Natural Language Development.

One frustration I do experience is that coding agents primarily interact via text, not visuals. Sometimes I wish to point to a specific area, but current browser automation tools (like Playwright MCP Server) aren’t quite adequate. Therefore, if new tools are needed to enhance coding agents, I believe the focus should be on richer visual interactions.

Conclusion

Agile methodologies rendered the specification document obsolete long ago. Do we truly need to resurrect it?

Spec-Driven Development appears to be conceived by individuals steeped in project management theory who envision removing developers from the loop entirely. I believe this is a missed opportunity to leverage coding agents to empower a new generation of developers—those who utilize natural language and build software iteratively.

Allow me to conclude with an analogy: coding agents are akin to the invention of the combustion engine. Spec-Driven Development confines them to locomotives, when our ambition should be to build cars, planes, and everything in between. Oh, and just like combustion engines, we should use coding agents judiciously if we are mindful of environmental impact.

Authors

François Zaninotto Marmelab founder and CEO, passionate about web technologies, agile, sustainability, leadership, and open-source. Lead developer of react-admin, founder of GreenFrame.io, and a regular speaker at tech conferences.

Comments