Spec-Driven Development (SDD): From Spec to Accepted Software
Spec-driven development (SDD) is an approach in which a written specification guides implementation and validation. In AI-assisted development, the spec gives people and coding agents a shared statement of what to build, why it matters, and how to check the result. GitHub describes this shift as making the specification central to the development process. [1]
For an outsourced team, the practical question is what happens between an approved request and accepted software. This guide proposes a working rule: every in-scope behavior needs an approved spec version, an implementation link, evidence, and an acceptance owner. The workflow and example below turn that rule into something a product owner and delivery partner can review together.
Key Takeaways
- Approve behavior before implementation: describe the user outcome, important exceptions, constraints, and explicit non-goals.
- Make handoffs reviewable: give each stage a responsible person, a versioned artifact, and a condition for proceeding.
- Inspect evidence at requirement level: a spec and code changing together is a review opportunity; acceptance still needs a demonstrated outcome.
- Start with one bounded feature: evaluate clarification work, traceable acceptance, and total delivery time before expanding the process.
Why AI-generated work can pass review and still miss intent?
Consider a feature that passes its automated checks but is rejected at the client demo. The code might satisfy the developer’s interpretation while missing the behavior the client expected. Microsoft’s SDD guidance identifies loss of intent across requirements, design, implementation, and validation as a problem to address. [2]
- The product owner sees different behavior: “Reject duplicates” was never clarified as applying within one file, within one customer account, or across the entire system.
- The engineering manager sees different versions: a business rule changes in a meeting, while the delivery partner continues from the previously approved document.
- The QA lead sees incomplete evidence: a completed task and a passing test suite do not show which business scenarios were actually checked.
These are illustrative handoff failures, not measured incident rates. Their shared cause is a missing agreement about behavior, version, and acceptance. That gap can leave scope questions unresolved until delivery. A useful spec makes those questions visible early and keeps the answers connected to the work.
What is spec-driven development?
You may also encounter the name specification-driven development. For this guide, the defining practice is to use explicit intended behavior to guide the work and evaluate the delivered result. The document’s length or file format does not establish that the practice is working.
Decide how long the spec must stay useful
In her practitioner analysis, Birgitta Böckeler distinguishes three levels: spec-first, spec-anchored, and spec-as-source. They describe different relationships between specifications and code, rather than a formal maturity standard. [3]
| Approach in that taxonomy | Relationship to the work | Question for your team |
|---|---|---|
| Spec-first | Write a spec to guide an initial task. | Will the document still describe the feature after acceptance? |
| Spec-anchored | Maintain the spec as the feature evolves. | Who updates it when approved behavior changes? |
| Spec-as-source | Treat the spec as the primary human-edited source from which code is produced. | Can your workflow reliably regenerate and verify the implementation? |
For a client–partner pilot, agree on the middle question before picking a tool: who maintains the accepted behavior description? Our recommendation is to retain an approved feature spec and a short change record so the next team member can understand what remains valid.
Place SDD alongside BDD and iterative delivery
Behavior-driven development (BDD) emphasizes business outcomes and shared examples that connect business, development, and testing perspectives. Those examples can make a feature spec more precise. [4] An acceptance example describes expected behavior; the surrounding SDD process also needs to connect that behavior to design, tasks, changes, and review.
The Agile principles welcome changing requirements and frequent delivery of working software. [5] A practical way to combine them with SDD is to specify one increment, review it, and update the agreement when learning changes the requirement. Freezing a large document is a project choice, not a prerequisite established by those principles.
This guide stays at the feature level. For the broader method of coordinating AI development roles and artifacts, see Bestarion’s BMAD Method guide.
How to run an SDD workflow with an outsourced team?
Use the following six-stage sequence as a starting agreement between the client and delivery partner. It adapts the specification, planning, task breakdown, and implementation sequence described by GitHub, with explicit ownership and acceptance checks added for this guide. [1] The role assignments are a proposed operating model, not a universal SDD standard.
Review requirements and design before splitting the work
The client should decide the intended business behavior; the delivery partner should make implementation assumptions and constraints visible. Review the design against the same approved behaviors before converting it into tasks. An unanswered question about an in-scope outcome should remain an open decision, rather than becoming a coding agent’s assumption.
| Stage and dependency | Accountable reviewer | Required output | Proceed only when… |
|---|---|---|---|
| 1. Frame the increment | Client product owner | Outcome, users, boundaries, non-goals, decision list | The team can say what this delivery includes and excludes. |
| 2. Approve behavior after framing | Product owner, with QA input | Requirement IDs, examples, exceptions, agreed spec version | Each in-scope behavior has an observable acceptance condition; unresolved behavior is excluded or resolved. |
| 3. Review design against the approved spec | Delivery technical lead | Design decisions, affected interfaces, constraints, unresolved technical questions | The design accounts for the requirements and identifies any proposed behavior change. |
| 4. Break the reviewed design into tasks | Delivery lead | Tasks linked to requirement IDs, dependencies, reviewer assignments | Every requirement has implementation and verification work assigned; extra work has a reason. |
| 5. Implement and check against the agreed version | Implementer and peer reviewer | Code changes, review notes, test results linked to the spec | Evidence addresses the stated scenarios and any deviation is resolved or explicitly deferred. |
| 6. Accept and preserve the delivered baseline | Named client acceptance owner | Requirement-level acceptance record and current spec | The owner accepts demonstrated behavior; changed, rejected, and deferred items remain visible. |
Keep implementation and acceptance on the same version
Include the spec version or commit identifier in the implementation task and review record. When the client changes a behavior, record the old rule, proposed rule, reason, affected requirement IDs, and approver. Then update the design, tasks, and checks affected by that decision before calling the work complete.
For example, changing invoice imports from “reject the entire file if any row is invalid” to “save valid rows and report rejected rows” changes observable behavior. Treat it as a spec decision with revised scenarios. Rewriting a sentence without changing behavior can follow the lighter documentation review your team agrees on.
Handoff check: ask the next reviewer to name the approved version and explain one exception without consulting the original author. If they cannot, clarify the artifact before moving to the next stage. This is a proposed review exercise; it does not establish a measured quality threshold.
What should a spec-driven development template include?
A useful template makes decisions inspectable. Use these fields for one feature, then remove fields that add no decision value. The template and invoice scenarios below are original examples created for this guide.
Capture behavior, boundaries, and unresolved decisions
| Spec field | What the team records | What a reviewer checks |
|---|---|---|
| Identity and ownership | Feature name; version; status; product owner; technical reviewer; acceptance owner | Who can approve behavior and which version is current? |
| User outcome and scope | User, intended outcome, included behavior, explicit non-goals | Can the buyer distinguish this increment from future work? |
| Behavior and examples | Stable requirement IDs; trigger; preconditions; expected result; failure cases | Could two reviewers reach the same pass/fail decision? |
| Constraints and dependencies | Relevant interface contracts, existing behavior to preserve, agreed quality constraints | Are constraints explicit and verifiable, or still decisions to resolve? |
| Open decisions | Question; decision owner; affected IDs; consequence of leaving it open | Should the affected behavior be blocked or excluded from this increment? |
| Delivery and acceptance links | Design; tasks; code review; test or demonstration evidence; acceptor and date | Can a reviewer follow a behavior from approval to its delivered evidence? |
| Change record | Old and new rule; reason; affected evidence; approval; new version | Does the accepted spec still describe the delivered feature? |
SDD acceptance criteria should state outcomes that a reviewer can observe. Replace “handle invalid files correctly” with an agreed response and data effect. If a performance limit matters, obtain the threshold, workload, and measurement conditions from the responsible owner; do not invent a plausible number to fill the template.
Work through an illustrative invoice-import feature
Example only: an operations user imports invoice records from a CSV file into one customer account. The proposed scope includes validation, duplicate detection, and retry handling. It excludes invoice approval, payment execution, currency conversion, and the design of account authorization. These are sample product decisions for discussion, not financial rules or a real client result.
For this example, an invoice identity is the combination of customer account and invoice number. A file is accepted atomically: either all valid records are saved, or none are. A previously accepted batch is identified by customer account and batch ID. A retry uses an agreed comparison of the submitted file content. These definitions must be approved before the following scenarios are treated as acceptance tests.
| Requirement | Proposed rule and scenario | Evidence to attach | Acceptance decision |
|---|---|---|---|
| IMP-01 · Valid import | Given a new batch ID and valid rows with new invoice identities, importing the file saves each row to the selected account and returns an accepted result. | Test fixture, result, and stored-record check linked to the implementing change. | Product owner confirms the intended records and result are shown. |
| IMP-02 · Invalid row | Given one row with missing currency, reject the entire file; identify the row and missing field; save no invoice records. | Negative-case result plus a before/after check that no records were added. | QA reviewer checks evidence; acceptance owner confirms all-or-nothing behavior. |
| IMP-03 · Duplicate invoice | Given a repeated invoice identity within the file or one already stored in that account, reject the file; identify the duplicate; save nothing. Check both variants. | Two scenario results: duplicate within file and duplicate against stored records. | Product owner confirms the duplicate boundary and rejection outcome. |
| IMP-04 · Unchanged retry | Given a previously accepted account/batch ID and identical file content, return the prior accepted result without creating more records. | Initial submission and retry results, with record counts unchanged by retry. | Acceptance owner confirms the repeat submission has no additional data effect. |
| IMP-05 · Changed retry | Given that accepted account/batch ID with different file content, reject the retry and preserve the previously accepted records. | Changed-content fixture, rejection result, and preserved-record check. | Acceptance owner confirms that reusing an accepted batch cannot silently replace its content. |
This matrix is a Spec-to-Acceptance record. Add links to actual artifacts when using it; the example contains no claims that tests have run. Before implementation, also decide how to treat simultaneous submissions and how long retry records must remain available. If those questions affect the promised behavior, resolve them or narrow the scope explicitly.
The practical benefit of the matrix is inspectability: a reviewer can see that “duplicate” and “retry” mean different things here. It also exposes an incomplete delivery immediately. A task that implements the success path alone cannot satisfy the negative and retry scenarios.
Which SDD tools fit the artifacts you need?
Choose a tool by the work products and reviews your team needs to maintain. The comparison below describes maintainer documentation checked on September 7, 2026; it is not a performance ranking.
Compare the documented artifact workflows
| Tool | Documented workflow or artifacts | What to verify in your pilot |
|---|---|---|
| GitHub Spec Kit | A workflow covering specify, plan, tasks, implement, and converge, with optional clarification and cross-artifact analysis. [6] | Can reviewers find the current spec, implementation plan, tasks, and verification result? Decide which checks require a person. |
| Kiro | Specs organize requirements or bugfix information, design, and tasks. Feature specs can start from requirements or design; Quick Spec can generate artifacts without intermediate approval gates. [7] | Choose a path that supports your required review points. Do not assume every mode pauses for client approval. |
| OpenSpec | A change folder holds a proposal, specs, design, and tasks. Its documented flow includes proposing, applying, and archiving a change back into the specs. [8] | Check how approved changes update the ongoing specification and how reviewers distinguish proposed from accepted behavior. |
Test the handoff using the same bounded feature
Try one agreed feature with the same requirement set. Ask a product reviewer to inspect the spec, a developer to identify affected work, and a QA reviewer to find the expected evidence. Then change one rule and repeat the exercise. Record where each person needed clarification or manual reconciliation.
Our suggested selection criteria are whether the team can identify the current approved artifact, trace a change, and review evidence without reconstructing a chat history. A generated document is only a starting point if those checks still fail. Keep tool installation, pricing, and broader agent orchestration as separate decisions.
How do you verify a spec against delivered software?
Requirements traceability is the practical review task here: follow an approved behavior to the implementation, the evidence, and the acceptance decision. Start by distinguishing a signal that artifacts moved together from proof that a requirement was met.
Read the chart as a prompt for inspection
Spec and code changes in the same pull request
Share of sampled spec-touching pull requests; both bars use a 0–100% scale.
Also modified code: 81.2%
Did not also modify code: 18.8%
Chart summary: most sampled PRs that touched a spec also changed code in that PR; a smaller share did not.
Source and method: SpecMine preprint, Table I; July 2026 snapshot. The sample contains 5,992 spec-touching PRs from 581 public GitHub repositories, drawn from 11 tools with a repository selection threshold of at least 10 stars. Geography is unspecified. The second value is calculated as 100 − 81.2 = 18.8%. [9]
Interpretation limit: this descriptive subsample is not a census or an effectiveness study. Spec/code co-change does not prove complete or correct implementation; implementation may also occur in a separate PR. [9]
The review implication we draw is specific: when a spec and code change together, inspect whether they agree. When they change separately, require a link that lets the reviewer follow the same behavior across the records. Neither arrangement removes the need to check the result.
Check each requirement before recording acceptance
- Identify the agreement: does the evidence name the approved requirement ID and spec version?
- Inspect the implementation link: which code change implements the behavior, and what relevant parts were reviewed?
- Inspect the result: do tests or a recorded demonstration cover the stated success, failure, and boundary scenarios?
- Resolve mismatches: is unexpected behavior a defect, an approved requirement change, or explicitly deferred scope?
- Record the decision: who accepted the demonstrated behavior, when, and with which limitations?
To check for spec drift, compare the current intended behavior with what the delivered feature does and what the evidence demonstrates. If an implementation change alters behavior, update the spec through the agreed review path. If it only reorganizes internals while preserving behavior, review the relevant evidence and record why a behavior update was unnecessary.
Avoid asking an AI model to write both an ambiguous requirement and its only acceptance check without independent review. In this proposed workflow, the acceptance owner confirms the expected outcome first; a generated test still has to demonstrate that agreed outcome. This is a review rule for the pilot, not a claim that a particular tool guarantees correctness.
When should you adopt SDD or keep the process lighter?
Spec-driven development is a fit decision about uncertainty and review work. Use a bounded pilot to find out whether explicit behavior and traceable acceptance help your team enough to justify maintaining the artifacts. Microsoft also recommends starting with a bounded use case. [2]
Choose a feature with decisions worth making explicit
The following decision matrix is an editorial recommendation. It assigns no unsupported scores or universal effort thresholds.
| Situation | Suggested starting approach | Decision before implementation |
|---|---|---|
| Client and partner interpret a feature differently | Use a reviewed feature spec and acceptance matrix. | Can the product owner resolve the disputed behavior with concrete scenarios? |
| A change touches an existing interface | Specify changed behavior and the behavior that must remain stable. | Can the team identify the existing interface and regression evidence needed? |
| A small, well-understood change has an observable result | Use a concise issue with the requirement and verification note. | Would separate design and task documents add a real decision or review? |
| The team is exploring an uncertain product idea | Keep exploratory assumptions explicit; defer a delivery baseline until the intended behavior is clearer. | What must the exploration answer before the team can commit to acceptance conditions? |
Decide whether to expand, revise, or stop the pilot
Agree on the evaluation window before starting. Track the following measures for the pilot, and use comparable prior work only if a useful baseline exists. These are proposed measurement definitions, not published SDD benchmarks.
| Measure | How to record it | What to examine |
|---|---|---|
| Accepted behavior coverage | Requirements with linked evidence and recorded acceptance ÷ all in-scope requirements. Keep deferred requirements visible. | Which behaviors remain unevidenced or unaccepted, and why? |
| Clarification rework | Count items reopened because the requirement was ambiguous during the agreed observation window; record the reason. | Are repeated misunderstandings being resolved in the spec or merely discussed again? |
| End-to-end delivery time | Elapsed time from starting the feature spec to accepted delivery, including planning, review, and corrections. | Does any implementation saving survive the added specification and review work? |
Expand when reviewers can trace accepted behavior, important misunderstandings are resolved earlier in this team’s work, and the total effort is acceptable to the people doing it. Revise when the spec helps but documents duplicate decisions or approval ownership remains unclear. Stop or simplify when the team cannot maintain the artifacts or the review cost outweighs the value observed in the pilot.
Record the decision with the actual observations. Do not infer a productivity gain from generated code volume, completed tasks, or repository activity alone.
How Bestarion can help
Bestarion’s software development service describes AI support across discovery, planning, architecture, development, testing, and release, with structured workflows and human decision gates. [10] To discuss a feature-level pilot, bring:
- One feature and the business behavior you need to accept.
- The current architecture, interfaces, and constraints the delivery team must respect.
- The people authorized to clarify requirements and accept the result.
Use the first discussion to agree on scope, required artifacts, review ownership, and evidence for completion.
What to Keep in Mind
- Choose the feature and its non-goals before choosing the toolkit.
- Approve observable behavior, including meaningful exceptions, and name the acceptance owner.
- Keep the approved spec, implementation links, evidence, and acceptance record connected when requirements change.
- Evaluate one bounded pilot using actual review and delivery observations before extending the process.
References
- Den Delimarsky, “Spec-driven development with AI: Get started with a new open source toolkit,” The GitHub Blog, Sep. 2, 2025. Accessed: Sep. 7, 2026. [Online]. Available: https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
- Apoorv Gupta, “Spec-Driven Development: A Spec-First Approach to AI-Native Engineering,” Microsoft for Developers, Jun. 10, 2026. Accessed: Sep. 7, 2026. [Online]. Available: https://developer.microsoft.com/blog/spec-driven-development-ai-native-engineering/
- Birgitta Böckeler, “Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl,” martinfowler.com, Oct. 15, 2025. Accessed: Sep. 7, 2026. [Online]. Available: https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html
- Agile Alliance, “Behavior Driven Development (BDD),” Agile Alliance. Accessed: Sep. 7, 2026. [Online]. Available: https://agilealliance.org/glossary/bdd/
- Agile Manifesto authors, “Principles behind the Agile Manifesto,” Agile Manifesto, 2001. Accessed: Sep. 7, 2026. [Online]. Available: https://agilemanifesto.org/principles.html
- GitHub, “Spec Kit repository README,” GitHub. Accessed: Sep. 7, 2026. [Online]. Available: https://github.com/github/spec-kit
- Kiro, “Specs,” Kiro Documentation. Accessed: Sep. 7, 2026. [Online]. Available: https://kiro.dev/docs/specs/
- Fission AI, “OpenSpec repository README,” GitHub. Accessed: Sep. 7, 2026. [Online]. Available: https://github.com/Fission-AI/OpenSpec
- Shyam Agarwal and Bogdan Vasilescu, “SpecMine: A Large-Scale Corpus of Spec-Driven Development Artifacts,” arXiv, arXiv:2608.25202v1, Aug. 25, 2026. Accessed: Sep. 7, 2026. [Online]. Available: https://arxiv.org/html/2608.25202v1
- Bestarion, “Software Development,” Bestarion. Accessed: Sep. 7, 2026. [Online]. Available: https://bestarion.com/services/software-development/
