How I Practiced Spec-Driven Development (SDD): An Honest Retrospective
This is a real-world retrospective on applying Spec-Driven Development (SDD) end to end in an enterprise-facing digital-employee AI project. Rather than repeating the usual four-document walkthrough or tooling comparison, it focuses on three questions: what SDD actually changes, where an engineer's time is best spent, and how to tell whether you've fallen into a trap. You'll learn how to treat SDD as a working discipline instead of a template, why it complements rather than conflicts with agile, where its applicability ends, how the four documents and three gates fit together, reusable methods for writing specs, design notes, task lists, and code, a checklist of common pitfalls, and how the true cost of SDD gets redistributed.
1. Introduction: “What I got wrong” is rarer than “how to do it”
Over the past six months, SDD (Spec-Driven Development) has steadily gained traction in discussions about AI-assisted programming. Yet most write-ups stop at the level of “step demonstrations”: which four documents to write, what capability to invoke at each step, and what code comes out at the end. The genuinely scarce information is of another kind: which practices looked reasonable at first but turned out to be costly after a full round? Which lessons only surface over a long, real project?
This article records my actual experience running SDD through a complete cycle on a digital-employee AI project. The project targets everyday enterprise office scenarios and combines several capabilities—question answering and retrieval, task orchestration, tool invocation, and human fallback—across multiple modules and fairly complex business rules. With the help of an AI coding assistant, I went through the entire flow end to end: requirement spec → design note → task list → coding implementation.
Rather than discussing tool selection, this article answers three questions:
- What does SDD actually change? It changes the way an engineer thinks and the order in which work is done before any code is written.
- Where should time go? Into getting requirements and the solution right, not into typing.
- How do you know whether you’ve stepped into a pitfall? By giving checkpoints you can compare against and the reasoning behind them.
2. Re-understanding SDD: It’s a working discipline, not a document template
2.1 From “four documents” to “four disciplines”
Many teams treat SDD as equivalent to “four document templates.” They grab the templates, fill in the blanks, and consider the “spec phase” done. This is the most common and most expensive misunderstanding of SDD. A template is only the carrier of a discipline. Strip the discipline out and SDD asks the engineer to do three things:
- Before writing code, think the vague requirement through. Every “should,” “as much as possible,” or “in a friendly manner” in a requirement must be translated, during the spec phase, into descriptions that can be judged and verified.
- Before starting, actively surface your blind spots. Have you really understood the technology choices? Have you considered failure paths? Have you confirmed the upstream and downstream constraints? These questions must be exposed during the design phase, not discovered reactively during integration testing.
- At the end of each phase, stop and run a validation. The end marker isn’t “close enough,” but “all explicit checks have passed.”
These three disciplines share one trait: moving the cost of thinking forward. A basic principle in software engineering is that the later a defect is found, the more it costs to fix. An ambiguity that could be resolved with a single sentence during requirement review may, by the integration-testing stage, touch interfaces, data models, and test scripts; after release, it can become an incident and a loss of trust. The value of SDD is to use process constraints to force problems to surface earlier.
2.2 SDD and agile are not opposites
A common misunderstanding is that SDD means “heavy documentation, heavy process” and therefore conflicts with agile’s “small steps, fast iteration.” Look more closely and you’ll see the two address different phases. Agile emphasizes fast feedback and continuous delivery, targeting the rhythm after implementation; SDD emphasizes thinking clearly before acting, targeting the decisions before implementation.
What is really opposed to SDD isn’t agile—it’s the “code first” instinct: open the editor and write while you think, hoping the code will “grow” a clear structure on its own. For tasks with relatively stable requirements and simple logic, this instinct is indeed efficient. But in projects with complex requirements, multiple trade-offs, and the need to evolve over the long term, the cost of skipping upfront thinking keeps accumulating. A more pragmatic approach combines the two: within an iteration, first anchor the goal and boundaries with a spec and design, then deliver, validate, and gather feedback over a shorter cycle.
2.3 Applicability boundaries: SDD is not a master key
Every method has boundaries, and SDD is no exception:
- Projects that fit SDD: requirements that are relatively stable yet complex, spanning multiple modules, with a long cycle and long-term maintenance needs; or cases with clear compliance or audit requirements that need a record of the decisions behind them.
- Projects that don’t fit SDD: prototype validation where requirements are still in an exploratory phase and even the acceptance criteria aren’t yet defined; or one-off scripts with a very short expected lifespan. Applying the full process to these tasks means the upfront documentation cost may well exceed the task itself.
The judgment criterion is actually simple: SDD delivers the best return when the cost of “getting the direction wrong” is significantly higher than the cost of “thinking a little longer.”
3. The complete SDD workflow: four documents plus three gates
3.1 Overall flow
A complete SDD cycle can be summarized as four stages and three gates:
requirement spec ──Gate 1──▶ design note ──Gate 2──▶ task list ──Gate 3──▶ coding implementation↑ define what to build ↑ decide how to build ↑ split into executable steps ↑ implement and validate per plan└──────────────── change write-back & two-way validation ────────────────┘
The stages are not a simple linear progression but a closed loop: any gap or deviation found during coding should flow back to the upstream documents for correction, avoiding the split where “the docs say one thing and the code does another.”
3.2 Division of labor across the four documents
| Document | Question it answers | Core output | Primary readers |
|---|---|---|---|
| Requirement spec | What to build, and to what level | Functional scope, non-functional metrics, acceptance criteria, explicit non-goals | Product, business stakeholders, engineering |
| Design note | How to build it, and why this way | Architecture choices, module breakdown, interfaces and data models, failure handling, observability | Engineering, testing, operations |
| Task list | In what order to build it, and how to validate | Ordered, independently executable tasks with acceptance criteria | Engineering |
| Development log | What was actually done, and why it deviated | Change trail, reasons for deviation, lessons learned | The engineering team itself |
The four documents build on each other: the spec defines the “destination,” the design plans the “route,” the tasks divide the “segments,” and the development log keeps the “trip notes.”
3.3 The three gates: criteria for closing a phase
The purpose of a gate is to turn “I think this is basically written” into “all checks have passed.” Using this practice as an example, the three gates can be defined as:
- Gate 1 (spec complete): every functional requirement is verifiable, non-functional metrics are measurable, scope and priority are agreed, the non-goal list is explicit, and it has passed at least one walkthrough by someone else.
- Gate 2 (design complete): every functional requirement has a corresponding solution in the design, key decisions come with alternatives and rationale, and failure paths and observability plans are complete.
- Gate 3 (tasks ready): every task has clear inputs, scope of changes, validation method, and dependencies, with a granularity suited to a single execution.
A gate is not a ceremonial rubber stamp; it is a checkpoint that forces you to stop and validate. It keeps the quality of what flows into the next phase stable, rather than letting a vague input get amplified stage after stage.
4. Practical details and reusable methods
4.1 Requirement spec: turning vague descriptions into precise ones
Writing a spec feels less like free creation and more like “translating a colloquial business request into verifiable statements, sentence by sentence.” Three points matter here: granularity control, iteration rhythm, and walkthroughs by others.
4.1.1 Granularity control: several small specs beat one big one
At first I tried to cover the entire digital-employee system with a single, comprehensive spec. The result was that during coding, the AI coding assistant had to digest a large amount of background at once and showed obvious “attention scattering”: sometimes the output conflicted with the definition of some peripheral feature, sometimes it got stuck on details unrelated to the current task, and the relevance of the generated code dropped accordingly.
After reflecting, I changed strategy and split the requirements by functional domain into several relatively independent specs with clear boundaries, each focused on a single capability area—for example, “context management in multi-turn conversations,” “citation and traceability of knowledge retrieval results,” and “fallback strategies after a tool call fails.” The split brought three direct benefits:
- Sharper execution context: when each functional domain advances on its own, the AI needs to understand far less context, so generation quality is more stable.
- Clearer requirement boundaries: splitting is itself an act of asking “where does this capability begin and end,” and many vague gray areas become explicit at this step.
- More controllable delivery and validation: each functional domain can be validated independently, and problems are easier to locate.
A reusable judgment rule: if a single spec contains multiple feature points with no strong dependencies among them, or if you keep needing to add “other related features TBD” whenever you get stuck, it probably should be split.
4.1.2 Iteration rhythm: don’t aim to get it right in one pass, aim to be stable before coding
The requirement spec went through three or more rounds of iteration before it stabilized. The reason wasn’t writing quality but that each fresh review turned up new problems:
- After the first version, I found overlapping boundaries among several feature points;
- After walking a colleague through it, several statements I thought were clear but others couldn’t follow surfaced;
- When walking through real usage scenarios, I added conventions for handling abnormal inputs and concurrency.
The reasonable expectation is that the spec stays stable before coding begins, not that it’s a finished draft on the first try. Each iteration should have a clear trigger (review feedback, scenario walkthrough, technical constraint), to avoid churning for the sake of change or repeatedly overturning your own work.
4.1.3 Walkthroughs by others: the lowest-cost, highest-return validation
The first reaction after finishing a spec is often “finally done.” But the genuinely valuable move is to grab one or two colleagues and walk them through the spec from start to finish. This isn’t about “passing a review”; it exploits a simple fact: when you have to say each implicit assumption out loud, the corners you hadn’t thought through get exposed all at once. A single question from a colleague—“What if the user’s input is empty?” or “If this interface times out, is that a failure or an empty result?”—is enough to make you realize a definition is unclear or a boundary is fuzzy.
A spec document can use this structure:
# Spec: Citation and traceability of knowledge retrieval results## 1. Background and goalsState the business value in one sentence, and list the measurable goals for this work.## 2. Scope- Included: ...- Excluded: ... (explicit non-goals, to prevent scope creep)## 3. Roles and core scenariosTypical users + main flow + key exception branches## 4. Functional requirements (FR)FR-01: ... Acceptance: Given... When... Then...FR-02: ...## 5. Non-functional requirements (NFR)Measurable metrics for performance, availability, security, compliance, etc.## 6. Acceptance criteriaAn executable acceptance checklist, listed by functional domain## 7. Open questionsUnconfirmed questions, owners, and deadlines
Two points deserve special emphasis:
- Non-goals matter as much as functional requirements: explicitly stating “what we won’t do this time” effectively curbs later scope creep.
- Acceptance criteria must be judgeable: a statement like “the result should be accurate” cannot be validated, whereas “given that a target document exists in the knowledge base, when the user’s question matches that document, the answer must include a clickable citation to the original source” is judgeable.
4.2 Design note: the most time-consuming part, and the most worth investing in
4.2.1 Time and validation intensity
The design note is the most time-consuming part of the whole process. Even with a fairly good grasp of the project’s tech stack, this phase still took roughly a day and a half to two days and went through six or more rounds of validation. The reason isn’t length but that the design must hold across several dimensions at once: it must cover the spec functionally, be implementable technically, handle failure paths, and support observability. If any one dimension is under-considered, it can be magnified later.
The six rounds weren’t mechanical repetition; each had a different focus:
| Round | Validation focus | Typical checks |
|---|---|---|
| Round 1 | Requirement coverage | Does every functional requirement have a corresponding design |
| Round 2 | Architecture and dependencies | Are module boundaries clear, do external dependencies have alternatives |
| Round 3 | Interfaces and data models | Are fields complete, is version evolution feasible |
| Round 4 | Failures and exceptions | Timeouts, rate limiting, degradation, retries, and idempotency |
| Round 5 | Security and compliance | Permissions, data isolation, handling of sensitive information |
| Round 6 | Observability and acceptance | Are logs, metrics, and tracing sufficient to support acceptance and troubleshooting |
4.2.2 The most easily underestimated cost is learning
There’s a risk that must be called out upfront: if the design document references a technology you aren’t familiar with, then reading and understanding that technology itself consumes a lot of time. This time doesn’t belong to “writing the document”—it belongs to “filling knowledge gaps.” If you don’t reserve for it in advance, you can easily end up with “the document is written, but I don’t truly understand the solution inside it.” The consequence is that during coding you can’t effectively validate the AI’s output and can only accept it passively.
So during the design phase, it’s worth explicitly separating two kinds of work: the thinking time genuinely spent on the design, and the learning time spent closing technical knowledge gaps. For unfamiliar components, adopt a “validate the minimum first” strategy: build a minimal working prototype to exercise the key path, confirm its behavior, limitations, and failure modes, and only then write it into the design document. This is far more reliable than writing a solution from impression.
4.2.3 Let AI participate in validation, not just generation
With the help of an AI coding assistant, validation during the design phase can also be upgraded. One effective approach is “role-adversarial validation”:
- First have the AI play a senior reviewer who challenges the current design from angles like performance, security, and maintainability;
- Then have it play a test engineer who tries to enumerate inputs and scenarios that could break the system;
- Finally, a human decides which objections hold and which amount to over-engineering.
The key is that review feedback must pass human judgment. AI can quickly offer many perspectives, but prioritization and trade-offs should still be decided by engineers familiar with the business and constraints.
4.2.4 Record key decisions
The most valuable part of a design note is often not the final solution but “why we chose it and what we gave up.” For key trade-offs, it’s worth keeping a lightweight decision record with four elements:
- Background and constraints;
- Alternatives considered;
- The decision and its rationale;
- The costs and follow-on risks the decision brings.
When you look back at this record half a year later, it often explains “why we wrote it this way” better than the code itself does.
4.3 Task list: breaking the design into executable, verifiable units
The task list is often treated as a “quick afterthought,” but it actually determines the execution quality of the coding phase. A good task should meet three conditions:
- Independently executable: a single task can be completed in a relatively focused context, without depending on a lot of unexplained background.
- Independently verifiable: every task has a clear validation method—ideally an automated test or a reproducible validation step.
- Clear dependencies: the order among tasks is explicit, avoiding the “waiting on each other” deadlock during coding.
In practice you can use a task format like this:
Task: Add a unified fallback strategy for tool-call failuresInputs: exception-handling conventions from the spec, failure-handling section from the design docScope of changes: call orchestration module, unified error-code definitions, related unit testsValidation: add cases covering timeout / rate-limiting / abnormal-return scenarios; all must passDependencies: noneEstimated effort: 0.5 person-days
The value of the task list also shows up in “visible progress”: when every task has acceptance criteria, project progress no longer relies on the vague judgment of “almost there,” but can be quantified as how many acceptance items have passed.
4.4 Coding implementation: keeping AI working in a controlled context
Once you enter the implementation phase, the biggest variable isn’t coding speed but context management. Based on this practice, four lessons are worth fixing in place:
- Advance only one task at a time: provide the AI with the spec fragment, design points, and acceptance criteria for the current task, and don’t proactively load the rest, to reduce interference from irrelevant information.
- Lock down “non-negotiable constraints” promptly: foundational rules like naming conventions, directory structure, and error-handling style should be maintained as long-lived project conventions, to avoid re-explaining them in every conversation.
- Prefer “small, verifiable” output: have the AI produce one runnable increment at a time, along with its tests, rather than generating large blocks of code all at once.
- Keep key decisions in human hands: changes involving security, data, permissions, or external interface compatibility must be human-confirmed before merging.
At the same time, establish a “change write-back” mechanism: if, during coding, you find an ambiguity in the spec or a gap in the design, correct the upstream document immediately rather than “solving it in place” only in the code. Once the docs drift from the implementation, all the upfront investment in SDD quickly loses value.
5. Common pitfalls and a checklist to avoid them
During the retrospective, I organized the pitfalls I’d stepped into into a self-check list:
| Pitfall | Typical symptom | Consequence | Improvement |
|---|---|---|---|
| Treating SDD as template-filling | Copying the structure, filling in vague content | Docs can’t guide implementation | Every doc must answer concrete checks |
| Writing one spec that’s too big | One all-encompassing spec | AI context balloons, attention scatters, target drifts | Split by functional domain into several small specs |
| Ignoring learning cost | Citing unfamiliar tech in the design | Doc is written but the solution isn’t truly understood | Do minimal validation first, then write it into the design |
| Skipping validation by others | Starting to code right after writing | Blind spots only surface during integration testing | Walk through every spec with someone at least once |
| Tasks that can’t be validated | “Complete feature X” | Progress can’t be measured, quality has no basis | Give every task a validation method and tests |
| Docs drifting from code | Implementation deviations don’t flow back | Docs quickly become stale | Establish a change write-back mechanism |
| Forcing SDD onto unsuitable cases | Running the full process even for exploratory requirements | Upfront cost exceeds the task itself | Judge fit by cost vs. benefit |
The first three were the costliest pitfalls for me personally: the first turned upfront documentation into mere formality; the second directly caused repeated rework during coding; the third forced me to do another round of knowledge rebuilding after the design doc was “done.”
6. Time investment: where the real cost goes
Looking at the time distribution from this practice, one conclusion is somewhat counterintuitive: SDD doesn’t “save” time—it redistributes it.
- Under the traditional approach, time is mainly consumed by coding, debugging, and rework;
- Under SDD, a substantial share of the time moves forward into writing the spec, walkthroughs, and design validation.
But this upfront investment buys two changes: rework in the coding phase drops noticeably, and when a problem arises you can quickly locate whether it’s “the requirement wasn’t defined clearly” or “the implementation deviated,” instead of repeatedly trial-and-erroring in the code.
It’s worth noting that the specific time figures depend heavily on project complexity, individual proficiency, and familiarity with the tech stack, so their reference value is limited. What’s more worth paying attention to is the structural experience:
- The design note usually takes longer than expected, especially when unfamiliar technologies are introduced;
- The spec phase has very high marginal returns—one or two walkthroughs often eliminate most of the ambiguity;
- The task list is relatively small in investment but has a large impact on downstream execution quality, so it shouldn’t be skipped.
7. Advice for different stages
If you’re about to try SDD, you can proceed in this order:
- Start with a functional domain of medium complexity. Don’t take the whole system as your first sample.
- Write the spec clearly first, and have someone walk through it with you. This is the highest-ROI step.
- Budget for “learning” in the design phase. Do minimal validation first for unfamiliar technologies.
- Write validation methods into the task list. Make progress quantifiable.
- Control context during coding. One task at a time, small steps, verifiable output.
- Keep the change write-back habit. Keep the docs aligned with the code at all times.
If your team already has some accumulated experience, you can go further by distilling SDD’s checks into reusable templates and review checklists, turning the method from individual experience into a team asset. For example, you can organize a spec review checklist, a design validation checklist, and task-splitting guidelines into separate documents and keep them under version control, evolving alongside the project.
8. Conclusion: what SDD buys you is certainty
After running the complete SDD flow end to end, my biggest takeaway wasn’t “documentation matters” but “certainty matters.” The essence of SDD is to make explicit—as discussable, reviewable, and traceable documents—the implicit decisions that would otherwise be scattered across people’s heads, conversations, and on-the-spot judgment; and then to use the three gates to ensure each phase’s output reaches a deliverable standard.
It won’t make development faster—it clearly slows things down in the upfront phase; but it surfaces “what we got wrong” earlier, lowers the cost of rework, and turns AI-assisted coding into a controllable accelerator rather than an unpredictable amplifier.
For engineers, SDD isn’t a process spec you have to comply with, but a capability you can deliberately practice: thinking the vague through clearly, finding the blind spots, and writing the decisions down. Whether or not you use AI tools, this capability pays off over the long run.
