# Spec-Driven Development (SDD) in Practice: A Retrospective on Process Discipline and Pitfalls
A field report from running the full spec → design → tasks → develop workflow end to end on an AI agent project. It covers why SDD is a working discipline rather than a document template, how the four documents differ in purpose and effort, why spec.md needs the most careful granularity control, where the hidden time actually goes in design.md, how to slice tasks and context for AI coding tools, and the three mistakes that quietly break the process — plus when SDD pays off and when it doesn't.
Why write a retrospective at all
Spec-driven development has been very popular in the AI-assisted coding community over the past six months or so. But almost all of the write-ups cover how to do it; very few cover what goes wrong. This post isn’t meant to be another tutorial. It’s a retrospective of a real, complete run of the spec → design → tasks → develop workflow, and a record of what I actually walked away with.
The project was an AI system built around a digital-employee use case. The cycle was long enough to expose the problems that short experiments simply don’t have time to reveal. My motivation for writing this up is straightforward: to leave behind the pitfalls I hit and the practices I validated, for my future self and for other engineers going down the same path.
Re-understanding SDD: it’s a discipline, not a template set
Plenty of teams read SDD as “four document templates” and assume that filling in the sections in the right order is good enough. After running it once end to end, I’ve reached the opposite conclusion: the essence of SDD is working discipline. It forces you to stop and think at three specific points.
- Before writing code, it forces you to make vague requirements precise and explicit.
- Before you start, it forces you to actively hunt for technical blind spots and edge cases.
- Between stages, it forces you to pause and validate, instead of sprinting all the way to production only to discover you were off course.
This is the opposite of the “ship it and iterate” instinct in traditional agile. To be clear, SDD isn’t right for every project. For short-lived scripts with well-defined requirements, the extra documentation overhead can easily cost more than it returns. But for medium-to-large engineering work — where you genuinely have to think before acting, and especially where AI coding tools are part of the loop — SDD is a qualitative upgrade rather than a marginal one. The reason is that AI is strong at execution but extremely dependent on the quality of its input. The more precise the document, the more controllable the output.
The four documents: different jobs, different costs
The core principle is “docs first, code second.” What surprised me in practice is that the four documents have completely different natures, time budgets, and iteration cadences — you can’t treat them the same way.
1. spec.md: the anchor for requirements
spec.md turns fuzzy requirements into precise statements. Writing it feels a bit like assembly-line programming: you work through features one by one and scrutinize the wording sentence by sentence until there’s no ambiguity left.
My first lesson is to budget real time for it. This document took me at least a full day, and don’t write it in isolation. Walk a colleague through it. The value of that walkthrough is that a single question from someone else is often enough to reveal a feature that isn’t clearly defined or an edge case that got missed. Reading your own document over and over tends to produce the illusion that “I clearly explained this,” while an outside reader spots the hole immediately.
The second lesson is granularity control, which is also where people most often trip up:
# Anti-pattern: a spec that covers everythingFeature: build a complete data analysis platform, including data ingestion,cleaning, visualization, and report export...# Problem: functional domains are mixed — in the develop phase the context# balloons, attention gets scattered, and the output drifts from the goal# Good pattern: a small spec focused on a single functional domainFeature: add date-range filtering to the reports moduleConstraints: support start and end dates; default to the last 7 days;return a clear error message for invalid inputEdge cases: cross-timezone ranges, empty result sets, and very wide rangesthat require pagination
Splitting one large requirement into several small specs, each focused on a single clear functional domain, works far better than one comprehensive document.
The third lesson is iteration cadence. My spec.md went through more than three rounds before it stabilized. That wasn’t because I can’t write it correctly the first time — it’s because every walkthrough surfaced something new. The right expectation is not to get it right on the first attempt, but to iterate it to stability before you touch the code.
2. design.md: the most expensive stage, and the most critical
design.md takes the most time of anything in the process. Even though I was already familiar with the technical stack involved, it still cost me roughly 1.5 to 2 days and more than six rounds of validation.
There’s one hidden cost worth flagging: if the design references technologies you don’t know, then “reading and understanding those technologies” alone eats a substantial amount of time. That time isn’t document-writing time at all — it’s learning time. So when you plan the schedule, you can’t estimate design based on typing speed alone, or you’ll underestimate it badly.
The reason design needs repeated validation is that it’s the bridge from requirements to implementation. A vague technical decision — how state transitions, how errors are handled, how modules are decoupled — propagates all the way into task breakdown and the final code. Any shortcut you take in design gets repaid many times over during develop.
3. tasks.md: cutting the design into executable actions
The job of the tasks stage is to break the technical approach in design.md into a set of small tasks with clear boundaries that can be verified independently. A good task list has three characteristics:
- Atomicity: each task maps to a single verifiable goal, which eliminates the ambiguous “half done” state.
- Verifiability: every task carries its own acceptance criteria, so you can tell definitively whether it’s met.
- Explicit dependency order: dependencies between tasks are called out, which makes it easier to plan the execution sequence.
The value here is that it converts “implementation,” a huge and intimidating activity, into a series of small, fast steps that both the AI and you can confirm easily.
4. develop: letting the AI work inside a controlled context
By the time you reach the development stage, spec, design, and tasks have already compressed and structured the context, and the output quality from AI coding tools is noticeably more stable. The core technique is simple: feed the AI only the document slice relevant to the current task, rather than dumping the entire project into the context window. The cleaner the context, the more focused the model’s attention, and the lower the chance it drifts from the goal.
The three pitfalls I hit most often
- Treating SDD as a fill-in-the-blank template. Caring only about whether the format is complete, not about whether the thinking is actually done, makes the whole exercise pointless.
- Making the spec too big. An oversized spec directly inflates the context burden during develop, and the tradeoff isn’t worth it.
- Underestimating the learning cost of design. Leaving time to understand unfamiliar technologies out of the schedule, and then losing control of the overall timeline.
Conclusion: who is SDD for
SDD isn’t a silver bullet. It spends “think it through up front” to buy “far less rework later.” If you’re working on medium-to-large projects where requirements keep getting clarified, where AI is part of the workflow, and where quality actually matters, this process delivers a step change. If your work is short, fast, one-off tasks, weigh carefully whether the investment pays off.
What makes SDD work was never the documents themselves — it’s the engineering discipline behind them: think clearly first, validate as you go, move in small steps.
