PaperlayerView exact revision on arXiv

Source-linked AI summary

Spec-Driven Development:From Code to Contract in the Age of AI Coding Assistants

Deepak Babu Piskala

arXiv:2602.00180v1cs.SEcs.AI

TL;DR

The paper addresses the problem of code becoming software’s de facto truth while requirements and design artifacts drift. It presents spec-driven development as a spectrum of practices that makes specifications authoritative and code generated, implemented, or verified against them, reporting improved code quality and reduced API-change cycle time in cited examples.

  • Problem

    Traditional development often leaves code as the de facto system truth while requirements, designs, and tests drift or follow implementation.

  • Method

    The paper develops a practical SDD framework in which specifications are authoritative, code is derived or checked against them, and rigor ranges from spec-first to spec-as-source.

  • Results

    SDD is presented as improving AI-generated code quality and coordination while reducing API-change cycle time by 75% in a financial-services case study.

  • Takeaways & Limitations

    Teams should match specification rigor to project needs, using enough discipline to remove ambiguity while avoiding unnecessary process.

Abstract

from arXiv · show

The rise of AI coding assistants has reignited interest in an old idea: what if specifications-not code-were the primary artifact of software development? Spec-driven development (SDD) inverts the traditional workflow by treating specifications as the source of truth and code as a generated or verified secondary artifact. This paper provides practitioners with a comprehensive guide to SDD, covering its principles, workflow patterns, and supporting tools. We present three levels of specification rigor-spec-first, spec-anchored, and spec-as-source-with clear guidance on when each applies. Through analysis of tools ranging from Behavior-Driven Development frameworks to modern AI-assisted toolkits like GitHub Spec Kit, we demonstrate how the spec-first philosophy maps to real implementations. We present case studies from API development, enterprise systems, and embedded software, illustrating how different domains apply SDD. We conclude with a decision framework helping practitioners determine when SDD provides value and when simpler approaches suffice.

I. INTRODUCTION

Spec-driven development makes specifications authoritative and code derivative, addressing the ambiguity and drift that make intent difficult for humans and AI assistants to recover. The paper presents SDD as a practitioner-oriented approach spanning principles, tools, workflows, case studies, and adoption guidance.

  • Motivation: Code-centric development leaves requirements, designs, and tests vulnerable to drift, making code the de facto system truth.Stakeholders and developers must often reconstruct intent from implementation.
  • Core principle: SDD treats the specification as the source of truth and lets code derive from intended behavior.Specifications are used by humans and machines to understand, build, and maintain systems.
  • Approach: SDD reduces ambiguity by expressing requirements as clear specifications that guide implementation rather than relying on coding first.A concrete photo-upload specification supplies the constraints needed to match implementation with intent.
  • AI catalyst: AI coding assistants can produce plausible but inconsistent outputs when vague prompts leave requirements unstated.Loose requests force guesses about formats, permissions, limits, storage, and other design choices.
  • Paper scope: The paper guides practitioners through specification rigor levels, workflows, tools, case studies, and decisions about when simpler approaches suffice.Its scope includes traditional BDD frameworks and modern AI-assisted toolkits.

A. Spec-First: Guided Initial Development

SDD spans increasing specification authority, from writing a spec before coding to maintaining it alongside code or generating all code from it. Greater rigor improves alignment but demands more discipline and trusted tooling.

  • Spec-First: Spec-first development writes requirements before implementation but may allow the specification to drift after coding.Its lower maintenance burden suits prototypes, one-off features, and initial AI-assisted development.
  • Spec-First: Spec-first is particularly useful for AI-assisted initial feature development because upfront requirements prevent the assistant from guessing.It does not protect long-maintained codebases from drift, where spec-anchored approaches may be preferable.
  • Spec-Anchored: Spec-anchored development maintains specifications with code and uses tests or scenarios to detect divergence.BDD scenarios, OpenAPI specifications, and contract-testing tools provide concrete implementations of this alignment.
  • Spec-as-Source: Spec-as-source lets humans edit only the specification while code is generated and regenerated from it.This can eliminate drift by construction, but requires mature generation tooling and confidence in generated code.
  • Choosing rigor: The specification spectrum increases specification authority over code while also increasing the discipline required to maintain alignment.Spec-as-source is established in some code-generation domains but remains practical only where generation quality is trusted.

III. THE SDD WORKFLOW

The SDD workflow creates a chain of accountability in which each phase produces an artifact that guides the next. Human review at checkpoints keeps implementation aligned with intent.

  • Workflow: Each SDD phase produces an artifact that constrains and guides the following phase.The workflow links intent to implementation through a chain of accountability.
  • Workflow: Human review at each workflow checkpoint verifies that successive artifacts remain aligned with intent.Review is part of the workflow rather than an activity reserved for the end.

A. Phase 1: Specify

The specify phase defines what the software should do through behavior-focused, testable requirements without prescribing implementation. Clear specifications capture success criteria, constraints, edge cases, and error conditions while avoiding unnecessary detail.

  • Specify: The specify phase produces a functional specification describing behavior, requirements, and acceptance criteria without prescribing implementation details.It separates what the software should do from how it should be built.
  • Specify: Teams express expected behavior through user stories, scenarios, acceptance criteria, and input-output examples.Business rules, constraints, edge cases, and error conditions are identified before implementation.
  • Specification quality: Effective specifications are behavior-focused, testable, unambiguous, and complete enough to cover essential cases.They should provide clarity and self-checks without over-specifying implementation.
  • Specification quality: Specification detail should increase only when ambiguity would permit multiple interpretations.When one interpretation is reasonable, additional detail can constrain implementation unnecessarily.
  • Plan: The plan phase translates functional intent into constraints covering architecture, data, interfaces, technologies, and non-functional requirements.These constraints give implementation and AI assistants context about system structure and conventions.
  • Implement: Implementation breaks the plan into reviewable tasks, produces code, and checks that code against both the specification and plan.Small validated increments enable frequent checkpoints and help prevent drift from compounding.

D. Phase 4: Validate

Validation checks whether implementation meets the specification through automated verification and human judgment, preserving the specification as the authority when gaps appear.

  • Validation purpose: Validation combines automated verification with human judgment to determine whether the code meets the specification.The phase closes the loop between what was specified and what was built.
  • Validation activities: Tests can run at unit, integration, and acceptance levels, alongside BDD scenarios, non-functional reviews, and stakeholder acceptance testing.
  • Handling gaps: When gaps appear, teams either revise an incorrect specification or fix code that fails a valid specification.In both cases, the specification remains authoritative and violations are addressed rather than ignored.
  • AI-assisted validation: Human-refined specifications can reduce LLM-generated code errors by up to 50%, although empirical evidence remains nascent.
  • Challenges and safeguards: LLM non-determinism remains a challenge, while property-based testing can verify specification invariants across implementation variations.In safety-critical domains, SDD combines LLM generation with formal verification for standards compliance.
  • Planning and execution: Self-spec methods separate planning from execution by having agents draft specifications that humans review before implementation.This can catch requirement misunderstandings before code is written.

A. Behavior-Driven Development (BDD) Frameworks

BDD turns specifications into readable, executable scenarios that connect stakeholder requirements with implementation, while newer AI-assisted tools structure coding around reviewed specification artifacts.

  • BDD foundations: Gherkin expresses BDD specifications as structured Given/When/Then scenarios that can be read by stakeholders and executed as tests.
  • BDD frameworks: Cucumber, SpecFlow, and Behave execute BDD scenarios against applications, bridging business requirements and technical implementation.
  • BDD workflow: BDD scenarios are written before implementation and treated as authoritative descriptions of feature behavior, with passing scenarios supporting confidence in documented requirements.
  • Specification-based APIs: API specifications such as OpenAPI, GraphQL SDL, AsyncAPI, and Protocol Buffers define contracts that support generation, parallel development, or strongly typed interfaces.
  • API contract verification: Contract testing tools verify that implementations match agreed API specifications, enabling frontend and backend teams to work in parallel with confidence.
  • AI-assisted workflows: GitHub Spec Kit structures AI-assisted development into specification, planning, task decomposition, and implementation phases with human review between stages.
  • AI-assisted tools: Kiro stages requirements, design, and tasks before code generation, while Tessl treats the specification as the maintained artifact from which code is regenerated.
  • Shared design principle: Separating planning from implementation lets agents execute within defined boundaries, reducing non-determinism associated with loosely prompted coding.

VI. CASE STUDIES

The case studies show SDD addressing integration incompatibility and requirement ambiguity by making specifications shared, reviewable contracts before or alongside implementation.

  • API-first microservices: Financial microservices suffered integration failures because teams implemented independently against incompatible assumptions about API contracts.
  • API-first microservices: OpenAPI specifications defining endpoints, schemas, and errors were reviewed by consumer teams before coding, moving integration discussions earlier.
  • API-first microservices: Specmatic generated mock servers for parallel frontend work and failed CI builds when implementations deviated from their specifications.
  • API-first microservices: 75% reduction in API-change cycle time followed adoption, as incompatibilities were caught during specification review rather than in production.
  • Enterprise requirements: An enterprise team faced disputes and rework because developers, product managers, and QA lacked a shared definition of feature completion.
  • Enterprise requirements: Product managers wrote Gherkin scenarios and developers automated them as tests, making a feature complete only when all scenarios passed.
  • Enterprise requirements: The scenarios became a shared language and authority, allowing stakeholders to validate intent and resolve disputes by updating scenarios or fixing code.

C. Case Study 3: Model-Based Embedded Development

The embedded case study uses a verified model as the specification and generates code from it, aligning implementation with safety requirements while shifting developer work toward specification and oversight.

  • Safety-critical motivation: An automotive supplier needed traceable engine-control software for ISO 26262 certification, but manual coding made certification laborious and error-prone.
  • Model-based specification: Simulink block diagrams and state machines served as the specification, allowing engineers to simulate and verify control behavior before code existed.
  • Certified generation: Certified generation produced C code from the verified model, and engineers changed the model rather than editing generated code.
  • Spec-as-source: Spec-as-source makes the model the only human-modified artifact while the implementation is entirely generated.
  • Redefined developer work: SDD shifts developers toward orchestrating specifications, reviewing AI outputs, and making high-level design judgments, while introducing challenges in maintenance and tool mastery.
  • Legacy systems: In brownfield systems, teams can encode existing behavior as specifications to verify that modernization preserves required functionality.
  • Cross-domain role: Across greenfield, brownfield, and embedded contexts, developers shift from code producers toward specification authors and AI orchestrators.

VIII. WHEN TO USE SDD

SDD provides value when ambiguity, coordination, traceability, or maintenance justify specification effort, but its rigor should match project needs. The paper recommends minimum sufficient rigor while warning against over-specification, drift, bureaucracy, tooling overload, and false confidence.

  • When SDD adds value: SDD adds value for AI-assisted development, complex requirements, multiple maintainers, integration-heavy systems, regulated domains, and legacy modernization.Specifications reduce ambiguity, support validation and coordination, preserve documentation through turnover, provide traceability, and enable reimplementation from existing behavior.
  • When SDD is overkill: Throwaway prototypes, solo short-lived projects, exploratory coding, and simple CRUD applications may not justify elaborate specification investment.In these contexts, specification overhead can exceed benefits or constrain learning when requirements are obvious or still emerging.
  • Choosing rigor: Use the minimum level of specification rigor that removes ambiguity: spec-first for AI-assisted initial development, spec-anchored for long-lived production, and spec-as-source only with mature trusted generation tooling.This decision framework matches rigor to project needs rather than treating one SDD approach as universally appropriate.
  • Common challenges: Over-specification turns specifications into pseudo-code, constraining implementation and eliminating the abstraction benefit of separating what from how.The paper recommends keeping specifications focused on the ambiguity they need to remove.
  • Common challenges: Specification rot occurs when code changes without corresponding spec updates, eroding trust unless automated tests expose divergence.Tests that fail when specification and code diverge make drift visible rather than silent and accumulating.
  • Common challenges: Passing spec tests does not guarantee correct software because an incorrect specification can be implemented faithfully.Specifications require careful review of requirements and do not eliminate human judgment.

X. SDD VS TRADITIONAL DESIGN DOCUMENTS

SDD differs from traditional design documentation primarily through enforcement and alignment, not because traditional engineering lacks specifications. It makes specifications executable, continuously validated, and consumable by AI coding assistants.

  • The problem of drift: Traditional software engineering already produces requirements, architecture, low-level design, and interface specifications, but these artifacts often drift from implemented behavior.As documents become outdated, code becomes the de facto truth and documentation becomes historical material that teams no longer trust or update.
  • Enforcement: Traditional design documents are advisory, whereas SDD specifications are enforced through failing tests and, in spec-as-source systems, code regeneration.The distinction concerns how specifications are used and maintained in relation to code.
  • What SDD adds: SDD adds executable specifications, CI/CD validation on every commit, and structured specifications that AI assistants can use to generate code and tests.These mechanisms catch divergence earlier and reduce the need for assistants to infer intent from vague prompts.
  • Continuity with existing practice: SDD extends an established specification-first idea through better tooling, mature CI/CD enforcement, and AI consumption rather than replacing existing development practices.The paper characterizes SDD as an evolution of earlier practices rather than a wholly new development philosophy.

XI. RELATIONSHIP TO EXISTING PRACTICES

SDD builds on TDD, BDD, DDD, and Agile practices while extending specification-first discipline to broader system scopes and AI-assisted development. Its central shift is making specifications authoritative as AI increases the value of clear intent.

  • TDD: SDD extends TDD’s unit-level specification discipline to features, systems, and architectures.A test written first functions as a micro-specification of expected behavior, while SDD applies the same principle at broader scopes.
  • BDD: BDD is the most direct ancestor of modern SDD because executable Gherkin scenarios connect business requirements with technical implementation.AI-assisted SDD tools add code-generation assistance that accelerates the path from scenarios to working software.
  • DDD: DDD’s ubiquitous language supports specifications that use shared domain vocabulary understandable to both developers and stakeholders.The connection is based on DDD’s emphasis on a common language across technical and business participants.
  • Agile: Agile artifacts such as user stories, acceptance criteria, and the Definition of Done become authoritative in SDD and are aligned through automation rather than human discipline alone.The difference is emphasis on enforcement and authority, not incompatibility with Agile methods.
  • AI-assisted development: SDD makes specifications authoritative and code derivative, shifting the bottleneck toward specification quality as AI generates code faster than humans type.Specifications remove ambiguity for both developers and AI assistants, while three rigor levels accommodate different project needs.
  • AI-assisted development: SDD adapts decades of TDD and BDD practice for the AI era, with developers increasingly orchestrating specifications, reviewing AI outputs, and focusing on high-level design.The paper presents this as a change in work emphasis enabled by tooling and AI capabilities.
Loading 2602.00180v1…