Spec-Driven Development (SDD) revives the old idea of heavy documentation before coding – an echo of the Waterfall era. While it promises structure for AI-powered programming, it risks burying agility under layers of Markdown. This post explores why a more iterative, natural-language approach might be better for modern development.
Coding assistants are intimidating: Instead of an IDE full of familiar menus and buttons, developers are left with a simple chat input. With so little guidance how can we be sure the code is correct?
To help people write good software with coding assistants, the open-source community has designed a clever way to guide a coding agent. Based on the initial prompt and some instructions, the LLM prepares a product specification, an implementation plan, and a detailed list of tasks. Each document depends on the previous document, and users can edit the documents to refine the specifications.
Ultimately, these documents are handed over to a coding agent (cloud code, cursors, Copilot, you name it). Now a properly directed agent should write solid code that meets business requirements.
This approach is called Spec-Driven Development (SDD), and several toolkits can help you get started. to name a few:
If you want to compare these tools, I recommend the excellent article Understanding Spec-Driven-Development: Kiro, Spec-Kit, and Tessel, written by Birgitta Böckeler.
What does a specification look like? It’s basically a bunch of Markdown files. Here’s an example using GitHub’s spec-kit, where a developer wanted to display the current date on a time-tracking app, resulting in 8 files and 1,300 lines of text:
Here’s another example of using Kiro for a small feature (adding a “Referenced by” field to contacts in Atomic CRM):
Requirements.md – Design.md – Tasks.md
At first glance these documents appear relevant. But the devil is in the details. Once you start using SDD, some of the drawbacks become apparent:
- context blindness: Like coding agents, SDD agents find context through text search and file navigation. They often miss existing functions that need updates, so review by functional and technical experts is still necessary.
- markdown madness: SDD produces a lot of text, especially in the design phase. Developers spend most of their time reading long Markdown files, looking for basic mistakes hidden in overly verbose, expert-sounding prose. It is tiring.
- organized bureaucracy: The three-step design process is excessive in most cases. Specifications include multiple repetitions, hypothetical corner cases, and excessive refinement. They seem as if they were written by some nosy clerk.
- Fake Tight: SDD toolkits generate what they call “user stories”, but they often misuse this term (e.g. “As a system administrator, I want the referential relation to be stored in the database” is not a user story). It doesn’t cause bugs but it is distracting.
- double code review: The code is already included in the technical specification. Developers will need to review this code before running it, and since it will still contain bugs, they will need to review the final implementation as well. As a result, review time doubles.
- false sense of security: The SDD method is meant to keep coding agents on track, but in practice, agents do not always follow the specification. In the example above, the agent marked the “Verify Implementation” task as completed without writing a single unit test – instead it wrote manual testing instructions.
- board of trusteesSDD shines when starting a new project from scratch, but as the application grows, the specs often miss the point and development slows down. For large existing codebases, SDD is mostly useless.
Most coding agents already have a planning mode and a task list. In most cases, SDD adds little benefit. Sometimes, this also increases the cost of feature development.
To be fair, SDD helps agents stay on task and sometimes detect corners that developers might miss. But in my opinion, the compromise (spending 80% of your time reading instead of thinking) is not worth it.
SDD may not help much today as the toolkits are still new and document prompts need improvement. If that’s the case, we just have to wait for a few months until they improve.
But this is my personal opinion SDD is a step in the wrong directionIt attempts to solve a flawed challenge:
“How can we remove developers from software development?”.
It does this by replacing developers with coding agents and protecting those agents with careful planning.
In that sense, SDD reminds me of the Waterfall model, which requires extensive documentation before coding so that developers can easily translate specifications into code.
But developers have long not been the sole executors, and Big Design Up Front has proven to fail most of the time because it piles up hypotheses. Software development is essentially a non-deterministic processSo planning doesn’t eliminate uncertainty (see the classic No Silver Bullet paper).
Also, what is SDD really for? you should be one business Analyst to catch errors during the requirements phase, and a developer To catch errors during design. Thus, it does not solve the problem it claims to solve (removing developers), and can only be used by those rare individuals who are a master of both trades. SDD makes the same mistake as no code tools, promising a “no developer” experience but actually requiring developers to use them.
Agile methodology solved the problem of non-deterministic development by trading predictability for adaptability. I believe they show us a way where coding agents can help us create reliable software without dipping into Markdown.
Give a coding agent a simple problem, and it won’t derail. Instead of translating complex requirements into complex design documents, we should Break complex requirements into multiple simple requirements,
I’ve successfully used coding agents to build fairly complex software without even looking at the code, by following a simple approach inspired by the Lean Startup methodology:
- Identify the next riskiest assumption in the product.
- Design the simplest experiment to test this.
- Develop that experiment. If this fails, go back to #2. Otherwise, repeat starting at #1.
Here’s an example: This 3D sculpting tool with adaptive mesh, which I built in about 10 hours with Cloud Code:
I No specifications writtenWhen the agent misunderstood me or when my own idea wasn’t working well, I added small features one by one, perfecting the software, You can see my instructions in the coding session log: they’re often short and vague, and sometimes lead to deadlock, but that’s okay, When simple ideas are cheaper to implement, building in small increments is the fastest way to move toward a good product,
Agile methodology freed us from the bureaucracy of waterfall. They showed that close collaboration between product managers and developers eliminates the need for design documents. Coding Agents Supercharge AgileBecause we can virtually write the product backlog and watch it get built in real time – no mockups needed!
This approach has one drawback compared to niche-driven evolution: it has no name. “Vibe coding” sounds dismissive, so let’s call it natural language evolution.
However, I have one disappointment: coding agents use text, not visuals. Sometimes I want to point to a specific area, but the browser automation tools aren’t good enough (I’m looking at you, Playwright MCP Server). So if we need new tools to make coding agents more powerful, I think the focus should be on rich visual interactions.
Agile methodology eliminated the specification document long ago. Do we really need to bring it back from the dead?
Spec-driven development seems to be born from the minds of CS graduates who know their project management textbooks by heart and dream of removing developers from the loop. I think this is a missed opportunity to use coding agents to empower a new breed of developers who use natural language and build software iteratively.
I’d like to conclude with an analogy: coding agents are like the invention of the combustion engine. Niche-driven development keeps them confined to locomotives, while we should be building cars, planes, and everything in between. Oh, and like combustion engines, if we care about the environment, we should use coding agents sparingly.