Spec-driven development, Back to the Future?!
We rapidly forget about the past, our mistakes, our progress. In the blink of an eye, a new technology is erasing three decades of best practices. Agile was “invented” because of the heaviness and rigidity of waterfall / V model, unable to adapt to a rapidly changing world. Against the V model’s long specification and design phases, agile brought iterative, incremental delivery and fast feedback loops from the business, the same business that used to spend months if not more in Word before. And today, we are reviving this old habit and giving it a shiny name to make it more appealing. In this blog post, I’ll speak about the AI-powered revival of this method and how to embrace it without falling back into old traps.
Disclaimer: this blog post represents my personal thoughts and is not endorsed by AWS.
Spec-driven development (SDD)
In 2024 and early 2025, “vibe coding” was the buzzword. Thanks to generative AI, almost anyone could develop an application, in a couple of hours, without prior programming knowledge. But almost everyone faced the reality, applications were buggy, unmaintainable and definitely not production-ready. Something was missing to guide the LLM…
In July 2025, AWS was among the first to speak about “Spec-driven development” with the release of Kiro, introducing specifications as “super-prompts” and a structured approach: spec -> design -> tasks. The objective is to collaborate with AI on defining the intent (“what to do”), the design (“how to do”) and the plan (“when to do”), and then let AI handle the implementation. With that additional context and structure, the LLM is able to work better.
Then during the next three months, we saw the emergence of OpenSpec, Spec Kit and Tessl, that provide a similar workflow through CLI or skills, and then almost all IDEs adopted the same approach, either natively (“plan” mode in Cursor), or through libraries (Spec-kit in Copilot).
Alongside these tools, methodologies like BMAD and AIDLC emerged. These methods push the spec-driven mode one step further by generating extensive documentation ahead of code: project brief, functional and non-functional requirements, detailed architecture (components, business rules, infrastructure, etc.) and planning (units/epics, stories).
What’s wrong with that?
SDD isn’t inherently bad — it provides LLMs with richer context than unstructured vibe coding, which generally misses the mark on both execution and intent. No, the issue is not the tool but how we leverage it, or rather, the issue isn’t in the approach, but how we apply it.
What I’ve seen so far (and done myself) was using this approach to define a complete application. And this is exactly the V model trap: spending hours, days or even more defining the complete scope of an application, answering hundreds of AI-generated questions, reviewing thousands of lines of AI-generated markdown. Thanks to AI, it’s faster than before (days instead of months), but that’s not a good reason to come back to this:
- First because we want to keep that flexibility, that agility to modify the scope, the requirements, the business rules along the development, based on what has been developed so far.
- Second because specifying too much in advance is just creating stock, that will potentially go to waste because requirements change, priorities shift, or we discover better approaches once we start building. And that stock can also overwhelm the LLM context, resulting in poorer results. Remember that you need to provide just the right amount of context.
You could argue that with LLMs, it’s so easy and fast to make changes (both in specs and code), that you don’t really care anymore. That’s maybe true at a small scale, working on a side project for example, but certainly not at the enterprise level and with bigger scopes.
The solution isn’t to abandon specs, it’s to right-size them.
“Micro-specs” make the difference
In the same way microservices helped us scale systems by breaking them into small, independent units, micro-specs help us scale development by working from small, focused specifications rather than huge specs that must be reviewed upfront.
Micro-specs?
Micro-specs, inspired by Agile’s small increments over the V-model’s long tunnel, are focused specification documents targeting single features or components — keeping LLM context manageable while enabling rapid iteration and review cycles.
This mirrors how Agile user stories replaced massive requirements docs, letting teams deliver value continuously instead of waiting for a perfect upfront spec.
I’ve tried AIDLC and BMAD methods, and they work much better on brownfield (existing) than greenfield (new) projects, because incremental changes are naturally smaller in scope. So what? So let’s quickly create “brownfield” projects! Let’s start building something quickly and then iterate. I feel like I’m not telling anything new here, as this is what we do with agile for decades. But like I said in the introduction, I feel we quickly forget about lessons from the past.
How micro ?
Just like microservices, the answer depends on context, there is no one-size-fits-all rule: an epic, a user-story, a component or a service?
It will depend on different criteria:
- Task complexity: The more complex, the more you want to split. Beyond complexity, consider coupling and dependencies. If it touches many parts of the system, break it down, just like microservices.
- Tool/method: AIDLC and BMAD feel verbose and seem antinomic with “micro” but they are pretty good in the first phases to clarify what you want to build (product brief and PRD in BMAD, requirements in AIDLC). You can probably leverage this for epics or complex features. Kiro and spec-kit work well at the epic/user story level but might also add overhead on smaller tasks.
- Organization: Consider the number of teams/roles involved to review the spec. Split it so each group can own and iterate on its part independently, like “service per team” in microservices. And like in agile, align with sprint length so that you can map to something you can design, implement, and validate in a single iteration (e.g. 1–3 days).
- Value/outcome: Each micro-spec should deliver something you can demo or test on its own. Too granular means you’re just creating tasks, not specs — and you lose the agile principle of delivering working increments.
My workflow for greenfield projects
Things evolve so quickly — this might be outdated by the time you read it, but here’s my current approach using Kiro CLI + IDE. You can achieve the same with other tools (e.g. Spec Kit, custom commands/agents in Cursor/Claude Code).
Step 1: Product brief
I start by defining the product brief (PRODUCT-BRIEF.md) with the following:
- Executive summary + core vision (problem, solution, differentiators)
- Target users (personas, journey)
- Scope (MoSCoW prioritisation)
- Epics (goal, value, criteria, features, priority, dependencies)
BMAD (the analyst agent) does that pretty well. I’ve just slightly adapted the workflow and added the Epics, as inputs for steps 3/4.
🛠️ I’m using a custom agent in Kiro CLI for this step.
Step 2: Break down epics (optional)
When an epic is too large, I spend some time to break it down to something more “micro”, using the default Kiro CLI agent or in vibe mode in Kiro IDE (with the PRODUCT-BRIEF.md in context).
Step 3: Steerings/rules
Before diving into the requirements (functional / non-functional), I add my steering documents to specify everything the agent needs to know: preferred stack, architecture principles, framework & libraries to leverage, potential integration with 3rd party APIs or services, general agent behaviour, etc. Note that it’s still high level, I’m not yet at the coding standards level.
Step 4: Specifications/Design/Plan with Kiro IDE
The main work happens here. From an epic +PRODUCT-BRIEF.md + high level steering documents in context, Kiro does a pretty good job at splitting it in user stories and acceptance criteria.
I really like the output format: user stories have the formal user-oriented structure: “As a [persona], I want [goal/functionality], so that [benefit]”. Acceptance criteria are based on the EARS notation: “WHEN [optional trigger], THE [system name] SHALL [system response]”. This is easy to read for me and the agent. It is concise enough to be reviewed without feeling overwhelmed and fits well in agent context.
Step 5: Development
Now I’m ready to develop my epic/user stories. I use specialised Kiro CLI agents — Python developer, infra developer, frontend developer, etc. — each with their own MCP servers and steering docs tailored to the current epic’s spec/design/plan.
This keeps agent context lean and relevant — no future epics, no irrelevant language standards, just the right info for the current task.
Step 6: Validation
Validation phase is done by another custom agent in Kiro CLI with the same principle: only the current epic’s spec/design/plan and some dedicated steerings are added to the context. This agent will not only validate the code quality, security checks, but also the adequacy between implementation and requirements / acceptance criteria.
And for brownfield projects ?
The workflow is similar except that we leverage the project source code and existing documents as input rather than the project brief.
Conclusion
After two months with this workflow, I’ve seen a real difference across different aspects:
- Spec reviews are less tedious and are actually manageable: no more skipping thousands of markdown lines from exhaustion.
- The LLM context stays lean. I don’t hit the maximum anymore, thanks to the small specs and the dedicated agents.
- Code quality is also better, I spend ±75% less time asking for modifications (in vibe coding mode). Targeted specs and agent-specific steerings consistently give better output.
- But the real advantage is the restored agility, with true iterative development and the ability to adjust the scope and direction during the project.
Agile taught us that working software beats comprehensive documentation. AI doesn’t change that — it just makes both faster. The question isn’t whether to spec, but how much. Keep your specs micro, keep iterating, embrace changes that will inevitably come: stay agile!
