Spec-Driven Development Explained

Updated 5 July 2026

Spec-Driven Development is a methodology where detailed specifications, rather than code, serve as the authoritative source for deriving and validating implementations.
It employs traceability mechanisms, explicit work contracts, and coordinated agent roles to transform human intent into testable, generated code.
Empirical studies indicate that repository-grounded hooks and structured specifications enhance quality, reduce errors, and manage drift in AI-assisted workflows.

Spec-Driven Development (SDD) is a family of software-development approaches in which the specification is treated as the authoritative expression of intent and code is treated as a generated, derived, or continuously validated artifact rather than the primary source of truth. In recent AI-assisted software engineering, the defining shift is that the unit of work is no longer the isolated prompt, but a traceable development process with state, roles, artifacts, and validation; in that setting, SDD denotes not merely “write a spec first,” but a way of turning human intent into operational artifacts that can drive agentic coding while preserving reviewability and control (Macedo, 3 Jun 2026). A complementary practitioner-oriented formulation states the same inversion more directly: the spec declares intent, and the code realizes it (Piskala, 30 Jan 2026).

1. Definition and conceptual scope

SDD is best understood as an inversion of code-first development. In code-first practice, implementation commonly becomes the de facto truth because requirements documents, design diagrams, and tests drift or are written late. SDD reverses that hierarchy by making the specification authoritative and code derivative; one paper summarizes this as treating specifications as the source of truth and code as a generated or verified secondary artifact (Piskala, 30 Jan 2026). In AI-assisted development, this shift is sharpened because coding agents are effective at executing well-defined instructions but weak at inferring unstated intent, undocumented constraints, or implicit business rules (Piskala, 30 Jan 2026).

A comparative assessment of operational AI-development frameworks makes the scope of SDD broader than conventional “spec first” practice. It distinguishes a strong or full form of SDD from a lightweight form. In the full variant, the specification becomes a versioned set of requirements, acceptance criteria, plans, tasks, architecture, and policies; it persists across the cycle and acts as a source of truth for downstream steps. In the lightweight variant, intent is compressed into a more compact specification or prompt-like structure with lower process overhead and greater ease of adoption, but with thinner coverage of the full engineering process in complex scenarios (Macedo, 3 Jun 2026).

This distinction should not be confused with another taxonomy that classifies SDD by the authority the specification retains over time. That taxonomy distinguishes spec-first, in which a specification is written before coding primarily to guide initial implementation; spec-anchored, in which the specification is maintained alongside the code through the system lifecycle; and spec-as-source, in which the specification is the only artifact humans edit directly and code is regenerated from it (Piskala, 30 Jan 2026). Taken together, these accounts suggest two partly independent dimensions: process depth and lifecycle authority. One concerns how much of the development process is formalized; the other concerns whether the specification remains a living contract or becomes the sole editable source.

2. Structural elements of spec-driven workflows

One influential process taxonomy organizes SDD-like workflows along six dimensions: specification, context, roles, execution, validation, and portability (Macedo, 3 Jun 2026). These are operational rather than merely descriptive categories.

Specification asks how human intention becomes a work contract. At the weak end, that contract is little more than a prompt. At the strong end, it is a rich set of artifacts such as requirements, PRDs, plans, stories, tasks, acceptance criteria, and policies. Context asks what an agent must know before acting: repository documents, code, history, architectural decisions, rules, and evidence. Roles concern specialization and authority: who decides, who implements, and who reviews. Execution asks whether the framework only guides reasoning or also edits files, runs commands, or invokes tools. Validation concerns tests, checklists, gates, and human review. Portability concerns whether the workflow survives outside one vendor, model, IDE, or repository convention (Macedo, 3 Jun 2026).

Across heterogeneous frameworks, several recurrent mechanisms make specifications operational rather than merely documentary. Persistent artifacts stored in the repository turn specifications into durable contracts. Work contracts stage intent into obligations, narrowing ambiguity step by step. Traceability mechanisms preserve a visible path from instruction to implementation. Human review remains explicit in stronger frameworks. Agent coordination assigns analysis, planning, implementation, and review to different personas or agents rather than allowing a single model to improvise across all concerns (Macedo, 3 Jun 2026). This is the sense in which SDD becomes a process architecture rather than a prompt template.

A parallel line of work on API specifications generalizes the same idea beyond code-generation frameworks. In the Bosque API ecosystem, specifications are treated as the primary artifact for humans, agents, and tooling: they express what the system should do, constrain how it may do it, allow automated tooling to validate implementations and usage, and provide grounded context to AI agents that would otherwise guess about hidden assumptions or unsafe actions (Marron, 13 Jun 2026). Structured-specification work at repository level makes a similar argument in different terms: natural-language prompting is ambiguous and lossy, whereas structured artifacts such as Gherkin specifications, domain models, and signature models are more maintainable, less ambiguous, and more directly verifiable (Feng et al., 4 May 2026).

3. Process models and workflow patterns

The best-known workflow pattern in contemporary AI-assisted SDD is the staged cycle Specify → Plan → Tasks → Implement. In GitHub Spec Kit, this is further organized into commands such as constitution, specification, plan, tasks, and implementation, with optional clarification, analysis, and checklist phases (Macedo, 3 Jun 2026). The logic of this staging is not merely decomposition. Each phase produces an intermediate artifact that can be reviewed, traced, and validated before the next stage compounds an error.

A more minimal workflow appears in Currante, a Visual Studio Code extension for specification-driven code generation with LLMs. Its process is Specification → Tests → Function. The user writes a structured natural-language specification represented in TOML, the system generates an initial test suite, the user can inspect, explain, delete, or regenerate tests, and only then does the LLM generate the implementation (Rosa et al., 7 Jan 2026). In this formulation, the test suite is the executable specification for final code synthesis, and the main research question becomes how human intervention in specification and test refinement changes correctness, convergence speed, and iteration dynamics (Rosa et al., 7 Jan 2026).

Formal-methods work yields a different but closely aligned process model. Validation-Driven Development (VDD) treats specification-driven development as effective only when validation is central rather than deferred. Its workflow is: select a requirement, write a validation obligation (VO), implement the VO in the specification, verify the specification for internal consistency, and run the VO using a validation technique such as animation, simulation, testing, or model checking (Stock et al., 2023). VOs are analogous to proof obligations but target validation; they break overall validation into smaller pieces, attach them to requirements, and link them to refinement steps so that revalidation obligations remain visible when the specification evolves (Stock et al., 2023).

These workflows also clarify the relation between executable and non-executable specification. In spec-first and spec-anchored practice, BDD scenarios, tests, contracts, or models may serve as executable specifications. In spec-as-source practice, code generation from artifacts such as OpenAPI specifications or Simulink models becomes central, and human modification of generated code is explicitly disallowed (Piskala, 30 Jan 2026). The common feature is not a single notation, but the use of specifications to govern downstream implementation and acceptance.

4. Frameworks, taxonomies, and empirical assessments

A comparative study of six AI-development frameworks provides one of the clearest operational maps of current SDD practice. Using a three-point scoring rubric—0 = absent or incipient, 1 = partial, 2 = strong or central—it evaluates frameworks across the six dimensions and reports the following totals (Macedo, 3 Jun 2026):

Framework	Total	Process emphasis
GitHub Spec Kit	8	durable spec artifact; portability
OpenSpec	6	simplicity; unified specification
BMAD Method	10	phases and specialized agents
Get Shit Done (GSD)	4	context engineering
Spec Kitty	9	git worktrees; review and merge gates
Reversa	6	reverse documentation engineering
Spec-Flow	11	spec-plan-tasks-implement-optimize-ship

The significance of this comparison lies less in the ranking than in the convergence it reveals. Across otherwise different frameworks, the isolated prompt loses centrality and is replaced by persistent artifacts, work contracts, traceability, human review, and agent coordination (Macedo, 3 Jun 2026). At the same time, no framework strongly covers all six dimensions, which exposes a structural trade-off between process depth and portability (Macedo, 3 Jun 2026).

Repository-grounded evaluation reinforces this picture. Spec Kit Agents adds phase-level context-grounding hooks to a multi-agent SDD pipeline with PM and developer roles. In 128 runs covering 32 features across five repositories, context-grounding hooks improved judged quality by +0.15 on a 1–5 composite LLM-as-judge score, with Wilcoxon signed-rank, p < 0.05, while maintaining 99.7%–100% repository-level test compatibility (Taghavi et al., 7 Apr 2026). On SWE-bench Lite, augmentation improved baseline performance by 1.7 percentage points, reaching 58.2% Pass@1 (Taghavi et al., 7 Apr 2026). The design implication is that SDD is materially strengthened when each phase is grounded in repository evidence and validated before errors propagate.

Structured Spec-Driven Engineering (SSDE) addresses the same problem from the standpoint of repository-level code generation. In a pilot study over three MVC systems and five LLMs, the addition of structured specifications improved generation quality relative to natural-language-only inputs; in particular, adding a signature model yielded +7.82% average TPR and -2.47% standard deviation (Feng et al., 4 May 2026). Error analysis further showed that more than 70% of failures were due to errors detectable by static analysis, including invoking non-existent APIs, data-type mismatches, positional-argument mismatches, and references to non-existent variables (Feng et al., 4 May 2026). This supports the claim that SDD is valuable not only as documentation discipline but also as a substrate for automated checking.

5. Validation, traceability, and security

A central theme across SDD research is that the specification is only as useful as the validation and traceability mechanisms attached to it. VDD makes this explicit by centering validation obligations, which are logical formulas linked to requirements and refinement steps, so that specification growth remains requirements-centered rather than merely internally consistent (Stock et al., 2023). Currante operationalizes the same intuition differently: by forcing the workflow through test refinement before function generation, it studies how effectively humans can express intent via executable tests and how that affects pass rate, time-to-pass, and iteration behavior (Rosa et al., 7 Jan 2026).

Traceability can also be pushed into the code artifact itself. A cross-model empirical study compares three SDD frameworks under different traceability regimes and shows a replicated trade-off between determinism and verifiability. Mandatory inline requirement citations reduce output determinism relative to an uncited condition, but only the cited condition enables automated hallucination detection. The reported automated hallucination detection rate is 86.4% for Claude Sonnet 4.6 and 88.0% for GLM-5-turbo, versus 0% for all alternatives, with FPR = 0% across both studies (Panda, 28 Jun 2026). This establishes that line-level citation discipline makes requirement grounding machine-checkable, but at a measurable lexical-variability cost.

Security-oriented work extends SDD by arguing that functional behavior is often explicit in a specification while security behavior remains implicit, generic, or postponed. The proposed response is to turn security into a first-class specification artifact. The Multilayer Specification Security Model represents traceable relations between system entities, threats, risks, requirements, implementation rules, controls, verification scenarios, and evidence; its transition chain is System entity -> Threat/Risk -> Security requirement -> Implementation rule -> Code element -> Verification scenario -> Evidence (Grynets et al., 29 May 2026). In a backend-generation study evaluated against a hidden 221-test black-box API suite, modal failures decreased from 50 in the baseline to 42 with ASVS conditioning and 36 with Multilayer Security Model conditioning (Grynets et al., 29 May 2026).

Constitutional Spec-Driven Development adopts an even stronger position by placing a versioned, machine-readable security constitution above feature specifications, plans, tasks, and code generation. In a banking microservices case study, constitutional constraints addressing 15 constitutional principles and mapped to 47 code locations reduced security defects by 73% compared with unconstrained AI generation while maintaining developer velocity (Marri, 31 Jan 2026). A related benchmark, SeClaw, applies a specification-driven pipeline to agent-security evaluation by turning structured risk specifications into executable tasks and evaluating full execution trajectories rather than final responses alone; its metrics explicitly distinguish coverage, attack success, and the harmonic-mean attack score $F_{\text{attack}}$ (Cheng et al., 1 Jun 2026). Together, these lines of work treat security not as post-generation review but as a specification problem.

Although current discussion often centers on AI coding agents, SDD appears in several technical domains with different specification substrates. In distributed systems, Sedeve-Kit builds a specification-first pipeline around TLA ${}^+$ : developers define system specifications and invariants, model-check them, generate trace-based test cases, write code guided by the specification, instrument code with action anchor macros, and validate implementations by deterministic replay against model-derived traces (Guo et al., 15 Sep 2025). This is a strong form of spec-driven development in which the abstract design, executable traces, and concrete implementation remain tightly coupled.

In automotive systems, an integrated and iterative scenario-based method combines top-down BDD-style scenario modeling with bottom-up NLP-assisted extraction from existing textual component specifications. Requirements and tests are co-developed across abstraction levels through Test-Driven Scenario Specification, joint execution of inter-component and component scenarios, and sequence-diagram feedback (Wiecher et al., 2021). The resulting picture is not a linear refinement chain but a living specification space linking stakeholder scenarios, component behavior, and executable tests.

In pure mathematics, spec-driven development is recast as a method for complexity management within an interactive theorem prover. The process begins by isolating a target theorem, definition, or construction, extracting a specification when appropriate, recursively decomposing target and spec into lower-complexity parts, and using abstraction boundaries to separate external behavior from implementation details (Commelin et al., 2023). Here the specification is not a software requirement but an interface-like mathematical contract; the proof assistant enforces boundary discipline, dependency tracking, and refactoring safety (Commelin et al., 2023).

In AI for science, ARIA transfers the same logic to reproducible data analysis. Researchers specify analytical goals in natural language, while the system generates code, validates computations, and produces transparent documentation through a document-centric workflow linking command files, context, code, data, orchestration, and AI modules (Chen et al., 13 Oct 2025). The paper explicitly states that researchers define what they wish to analyze—the specification—while the system determines how to perform the analysis—the implementation (Chen et al., 13 Oct 2025). This suggests that SDD is not limited to program synthesis, but generalizes to any workflow where intent, execution, and evidence must remain coupled.

7. Trade-offs, risks, and open research problems

The main trade-off identified in current framework research is structural: deeper process control tends to reduce portability across agents, vendors, or environments, while lightweight and portable approaches tend to thin out roles, validation, or execution control (Macedo, 3 Jun 2026). Spec Kit and OpenSpec are relatively portable but lighter on some dimensions; BMAD is richer in roles and phased artifacts but more operationally heavy; GSD concentrates on context engineering but is weak on roles, validation, and portability (Macedo, 3 Jun 2026). This implies that SDD is not a single optimum but a family of design choices about where process should be explicit.

A second recurring limitation is that specifications do not prevent drift by themselves. Comparative framework work warns about drift between specification and code, excessive trust in generated artifacts, fragility of community extensions, platform dependence, and a lack of benchmarks for the complete process (Macedo, 3 Jun 2026). A related architecture paper reframes two AI-era failure modes more sharply as context explosion and silent spec-code drift, and proposes a machine-readable spec graph, a Spine context assembler, and a drift gate that makes divergence a blocking merge condition (Grabowski, 25 Jun 2026). This suggests that SDD becomes practically durable only when specification maintenance is mechanized rather than left to discipline.

Empirical work also exposes concrete cost trade-offs. In Spec Kit Agents, quality gains from repository-grounded hooks come with latency overhead: Baseline vs. Augmented is 14.4 min vs. 15.5 min, while Full vs. Full-Augmented is 24.0 min vs. 37.2 min (Taghavi et al., 7 Apr 2026). In citation-discipline studies, stronger traceability reduces determinism but uniquely enables automated hallucination detection (Panda, 28 Jun 2026). More broadly, the evidence base remains uneven: some comparative scoring is based on authors’ judgment from official documentation, sometimes by a single rater and with substantial grey literature (Macedo, 3 Jun 2026).

The current research agenda therefore shifts from asking whether LLMs can produce correct final code to asking whether specifications genuinely improve the full development lifecycle. Proposed priorities include process-oriented benchmarks, metrics for context grounding, studies of spec drift, installation security and permission governance, reproducibility, and longitudinal evaluations on real teams (Macedo, 3 Jun 2026). An explicit unresolved question is whether specifications truly reduce ambiguity or merely move ambiguity into a different artifact (Macedo, 3 Jun 2026). In that sense, SDD is less a settled method than a broad reorganization of software engineering around explicit contracts, intermediate artifacts, and continuously checkable alignment between intent and execution.