Spec-Driven Development (SDD): How a Complete Spec Cuts Rework in AI-Assisted Coding Through Granularity Control and Acceptance Criteria

    This article walks through Spec-Driven Development (SDD) and explains why a complete, well-scoped spec dramatically reduces rework in AI-assisted coding. Framed as a retrospective after delivering a long-running intelligent-agent project, it covers what SDD actually is (a work discipline, not a document template), what each of the four artifacts (spec, design, tasks, develop) solves and how much time to invest, why granularity control and verifiable acceptance criteria matter, eight pitfalls you only hit after running the full flow, reusable self-check lists, and when SDD is worth using versus when to skip it.

    Introduction: When Coding Gets Cheap, Thinking Clearly Gets More Expensive

    Over the past six months, Spec-Driven Development (SDD) has been a hot topic in discussions around AI-assisted coding. Most public write-ups focus on “how to write a spec,” and few cover “what goes wrong and what it costs.”

    I recently used SDD to deliver a long-running intelligent-agent (“digital employee”) project end to end, walking through the full “spec → design → tasks → develop” flow once more. Before turning my takeaways into a guide, I want to establish one premise: AI has multiplied the speed of generating code by several times, but the cost of mistakes is amplified the same way. Misunderstood requirements, missed edge cases, and a poorly chosen approach all get scaled up too. Previously, a wrong piece of logic was a few lines to fix; now, in SDD, a single misstated requirement can be amplified at every downstream stage and finally surface as “a lot of code was written, but the direction is wrong.”

    So this retrospective isn’t about “how magical SDD is.” It answers three concrete questions: What is the essence of SDD? What does each of the four artifacts solve, and how much time is it worth investing? And which pitfalls do you only hit after running the whole thing once?

    1. The Essence of SDD: A Work Discipline, Not a Document Template

    1.1 From “four documents” to “a work discipline”

    Many teams treat SDD as a set of four document templates and consider it done once the documents are delivered. But after running the full flow once, I believe its essence is a work discipline, embodied in three “mandatory” behaviors:

    • Mandatory clarity of thought: Before writing code, vague requirements must be turned into precise, verifiable descriptions. A sentence like “users should be able to export data” has to be pinned down to which fields to export, the data volume, whether it’s async or sync, and how failures are retried.
    • Mandatory exposure of blind spots: Before starting, you must surface the “I thought I knew, but I actually don’t” areas ahead of time — for example, the timeout behavior of a certain interface, or whether a certain kind of data is allowed to be null. If these blind spots aren’t exposed during design, they’ll all erupt at once during integration.
    • Mandatory stop-and-verify: At the end of each stage, you must stop and check the output against the previous stage. Are all requirements covered? Is the design implementable? Are the tasks independently verifiable? Rather than pushing straight from requirements to launch and only then discovering you’ve gone off course.

    Summed up in one sentence: SDD turns “thinking” into an explicit artifact that can be reviewed, reused, and traced. That is precisely what sets it apart from “just get it running first.”

    1.2 SDD is not opposed to “just get it running first”

    To be clear, SDD is not inherently opposed to agile or rapid experimentation. Rapid prototyping is suited to validating “whether the direction holds”; SDD is suited to ensuring “the solution is implemented correctly.” The two can be combined: use a small, quick validation to answer the direction question, then use SDD to answer the implementation question. The real issue isn’t “think first or build first,” but whether the ambiguous parts are explicitly recorded and given a review.

    1.3 In the age of AI-assisted coding, the value of SDD is amplified further

    Before large language models became widespread, if a requirement was unclear, a programmer would “fill the gap” using their own understanding. That process was slow, but at least a human did the translation in the middle.

    Now, ambiguous parts of a requirement get “smoothed” by an LLM into code that looks reasonable — and it happens very fast. The result: ambiguity is masked, not resolved. A poorly defined feature description can be turned into a well-structured implementation that even passes the tests, yet it may not solve the problem you actually wanted to solve. From this angle, the value of SDD in the age of AI-assisted coding is not adding process, but restoring that “human translation” step — and locking in the result of that translation.

    2. The Four Artifacts: Roles and Time Investment

    The core of SDD is “write the docs first, then the code.” But in practice, the four artifacts differ completely in nature, time investment, and iteration rhythm. Treating them as the same kind of “document” is where many teams’ execution starts to go wrong.

    2.1 What each of the four artifacts does

    Artifact Core question it answers Primary reader Essence
    spec.md What to build, and to what degree Stakeholders, peers, reviewers Contract
    design.md How to build it, and why this way The developer, technical reviewers Solution
    tasks.md In what order, and how to verify each step The developer Execution plan
    develop Does the result meet the agreement The developer, test/acceptance owners Implementation and acceptance

    There is a strict one-way dependency among the four: if requirements are unclear, the design will surely drift; if the design is unreasonable, task breakdown will surely be distorted; if tasks aren’t verifiable, there’s no standard for judging whether the implementation is right or wrong. Therefore, the quality of upstream artifacts determines the effectiveness of all downstream work — and that is the basis of how I allocate time.

    2.2 spec.md: the anchor for requirements

    The essence of spec.md is turning vague requirements into precise descriptions. The work is somewhat like assembly-line programming: go through the feature points one by one and refine the wording sentence by sentence. It must answer three questions: Whose problem are you solving, and what is it? What are the feature points, and where is the boundary of each? What level of completion counts as done?

    Time investment: At least a full day, and don’t write it in isolation.

    My approach is to write a first version alone, then walk a peer through it item by item. The value of that walkthrough isn’t how many suggestions the other person offers, but that you have to explain every item clearly in your own words. The places you can’t explain clearly are usually the corners you haven’t thought through yourself. A single offhand question from someone else can make you notice that a feature point is vaguely defined, an edge case isn’t covered, or an acceptance criterion can’t be verified.

    Granularity control: a single spec shouldn’t be greedy for scope. This is my first key takeaway. The biggest risk of a large spec isn’t the document itself, but what’s downstream: by the develop stage, AI coding tools need to understand all the feature points within one context at once. The context balloons rapidly and attention gets diluted, easily leading to “fixing one thing while breaking another” — one module gets implemented meticulously while another drifts off target. A better approach is to split by functional domain: one spec focuses on a single, well-defined domain, such as “customer profile management,” “conversation task scheduling,” or “report export,” with each domain designed, broken down, and accepted independently. For the same amount of work, splitting it up works far better than one big, all-encompassing document.

    Iteration rhythm: don’t aim to get it right the first time, but do stabilize it before you start. My spec.md went through 3+ rounds of iteration before it was finalized. This isn’t a writing-quality issue; each walkthrough exposes new problems. A suggested progression:

    1. Version 1: List all feature points yourself, focusing on answering “what to build.”
    2. Version 2: After the peer walkthrough, add edge cases, exception paths, and acceptance criteria.
    3. Version 3: Converge scope based on review feedback and make clear “what we’re not doing this time.”

    The third step is often overlooked. A good spec must state not only what to build, but also what not to build. An explicitly excluded scope is the most effective tool for resisting requirement creep later on.

    2.3 design.md: the most time-consuming, and most underestimated, step

    design.md is where the most time goes in the entire flow. I spent roughly 1.5 to 2 days here, and that’s on the premise that I’m already familiar with the tech stack involved in the design.

    One key note: if the design references technology you’re not familiar with, the cost of reading and validating that technology must be counted separately. It isn’t “writing-document” time, it’s “learning” time. For example, if the solution uses a certain message queue, some container orchestration capability, or a particular monitoring stack, you need to understand its delivery semantics, timeout behavior, retry mechanism, and operational cost before deciding whether it truly fits the current scenario. This time is frequently and severely underestimated, ultimately delaying the whole plan.

    My design.md went through 6+ rounds of verification. Each round wasn’t a re-read; it was checking with questions in mind. These questions roughly include:

    • Are module boundaries clear, and is there any overlap of responsibilities?
    • Do the failure modes on critical paths all have corresponding handling?
    • Can the data model support all the queries and statistical needs in the spec?
    • Does the solution introduce complexity the spec didn’t ask for?
    • If a dependency becomes unavailable, can the system degrade rather than go entirely down?

    When writing design, I value “why I didn’t choose a given option” more. Writing only the final solution throws away the evidence of this round of thinking. Later, when someone challenges “why not a simpler approach,” you’d have to re-derive it all over again. Recording the rationale for decisions is, in essence, saving time for the future.

    2.4 tasks.md: turning the design into independently verifiable execution units

    tasks.md maps the design onto an actionable checklist, and its quality depends on whether the breakdown granularity is right. The test is simple: each task should be the smallest unit that can be started, verified, and rolled back independently.

    Each task should contain at least the following:

    1. - [ ] T3 Implement timeout and retry for conversation tasks
    2. Basis: design.md §4.2
    3. Acceptance: Simulate a downstream timeout; return a degraded result within 10s, with no more than 2 retries
    4. Depends on: T1
    5. Estimated: 0.5 day

    The most common problem here is “tasks are written, but the acceptance criteria are left blank.” Without acceptance criteria, tasks in an AI-assisted coding scenario are almost bound to go out of control: you can’t tell whether the generated code meets the bar, and you can only wrap up on “looks close enough.”

    2.5 develop: execution in sync with documentation

    The principle of the develop stage is “advance one task at a time, and verify as soon as it’s done.” My rhythm: each time I finish a task, I first check it against the acceptance criteria in tasks.md, then move to the next task. If I find the actual implementation inconsistent with the design, I go back and fix design.md rather than “improvising” in the implementation.

    3. Real Pitfalls: Eight Problems You Only Hit After Running the Full Flow

    Pitfall 1: Treating SDD as “write four documents first.”
    The typical symptom is documents that look polished while the code is written casually, and the two gradually drift apart. The root cause is treating documents as deliverables rather than constraints. Documents only matter when “the code must conform to them.”
    Fix: Define a clear “downstream consumer” for each artifact. The consumers of spec are design and test cases; the consumer of design is tasks; the consumer of tasks is every commit. A document with no consumer will inevitably rot.

    Pitfall 2: Loss of control over spec granularity.
    As noted earlier, a large spec leads to context bloat and diluted attention. One more point: loss of granularity control also creates a management problem — a single spec covering five functional domains makes it impossible to tell “how much is done,” and impossible to make tradeoffs when a deadline slips.
    Fix: Split by functional domain, with one spec per domain, accepted independently. The criterion for splitting isn’t “whether the document is easy to write,” but “whether it can deliver value independently.”

    Pitfall 3: Underestimating the learning cost of the design stage.
    An unfamiliar technology choice gets treated as “just a quick look while writing the doc,” and you end up stuck halfway through the design, or you finish it only to find the choice doesn’t fit.
    Fix: Add a dedicated “technical assumptions to validate” section in the design. List the mechanisms to verify, how to verify them, and the deadline for verification. Manage it as an explicit work item, not something hidden inside “writing the design.”

    Pitfall 4: Letting AI coding tools “guess” ambiguous requirements.
    This is a pitfall new to the AI era. When requirements are ambiguous, the tool outputs a complete, reasonable-looking implementation; the ambiguity gets masked and only surfaces at acceptance.
    Fix: In the spec stage, explicitly mark ambiguous points as “TBD” and give a temporary assumption. All TBD items must be cleared before design begins, or explicitly written down as “not handled this cycle.”

    Pitfall 5: Tasks too coarse-grained or dependencies tangled.
    A task written as “complete the conversation module” is really three to five independent pieces of work. The result is that it can’t be parallelized, can’t be rolled back, and progress is invisible.
    Fix: Use “can it be completed and independently verified within half a day” as a rough rule of thumb for granularity, and explicitly note dependencies in the task list.

    Pitfall 6: Missing acceptance criteria.
    tasks list actions with no acceptance, leading to “it’s written, but I don’t know if it’s right.”
    Fix: Give each task at least one executable, observable acceptance criterion. If you can’t write one, it means the task isn’t thought through yet.

    Pitfall 7: Write the docs and then forget them.
    Once you enter develop, you stop revisiting the docs, and a month later no one can say why a given rule was defined the way it was.
    Fix: Agree on when to update the docs — change spec when requirements change, design when the approach changes, tasks when the plan is adjusted. Fold doc changes into the code review checklist.

    Pitfall 8: Using SDD where it isn’t needed.
    Writing four documents for a one-off script or a very short experiment costs far more than it returns, and the team ends up resenting it.
    Fix: Define SDD’s applicability boundary and allow a “lightweight SDD” — for example, a small change gets only a spec plus acceptance criteria.

    4. Reusable Method Checklist

    spec self-check list

    • Does every feature point have clear input, output, and boundary conditions?
    • Are exception paths covered (timeout, null data, concurrent conflicts, unavailable dependencies)?
    • Is there an explicit “what we’re not doing” scope?
    • Does every feature point have a verifiable acceptance method?
    • Is terminology defined consistently, avoiding one word referring to different things in different paragraphs?

    design self-check list

    • Are module responsibilities single and boundaries clear?
    • Do all critical failure modes have a degradation or retry strategy?
    • Can the data model support all query needs?
    • Are the rationale for key choices and the rejected options recorded?
    • Is there any over-design the spec didn’t require?

    tasks self-check list

    • Can each task be independently verified and independently rolled back?
    • Are dependency orderings noted?
    • Are acceptance criteria executable and observable?
    • Does the total task volume match the remaining time, and is there an obvious critical path?

    develop-stage discipline

    • Advance one task at a time; verify as soon as it’s done.
    • When the implementation is inconsistent with the design, fix the docs first, then the code.
    • After finishing each batch of tasks, go back against the spec to check whether any feature point was missed.

    5. Applicability Boundaries: When to Use It and When Not To

    Well-suited scenarios: requirements are relatively vague and need multi-party alignment; the project runs long and involves many people; it needs long-term maintenance and traceability; the change touches core paths where mistakes are costly.

    Not-well-suited scenarios: one-off scripts or temporary data processing; very short technical validations; changes where requirements are extremely clear and the modification is minimal. In these cases, direct implementation plus a light explanation is more cost-effective.

    My practical recommendation is to use it in tiers: core paths go through the full SDD, edge features use the lightweight version, and one-off tasks are done directly.

    6. Conclusion: Where the Real Value of SDD Lies

    After running the whole round, I’d summarize SDD’s value in three points.

    First, it moves time allocation forward. In the traditional model, most rework happens during development and integration; SDD pulls that thinking cost forward into the spec and design stages. The cost is being a bit slower early on; the payoff is being much steadier later.

    Second, it turns “understanding” into an asset. spec and design aren’t just for the present you — they’re the team’s shared understanding of the business and the system, directly usable when onboarding newcomers, handling requirement changes, or doing postmortems.

    Third, it makes AI-assisted coding controllable. When requirements are precise, the design is clear, and tasks are verifiable, AI coding tools become reliable executors rather than a black box that amplifies ambiguity into code.

    To sum up my experience in one sentence: SDD doesn’t slow development down; it makes “rework” visible and avoidable. It’s not for every project, but for teams and individuals who want to “think it through before acting,” it’s a real step up in quality.