{"slug": "what-is-spec-driven-development-the-spec-as-source-of-truth", "title": "What Is Spec-Driven Development? The Spec as Source of Truth", "summary": "Spec-Driven Development (SDD) is emerging as a workflow where a versioned specification serves as the source of truth for AI coding agents, addressing the ephemeral nature of prompts. The approach inverts traditional development by treating the spec as the primary artifact, with code generated or verified against it. This practice gains relevance in 2025 as AI agents require durable context to produce consistent output across sessions and team members.", "body_md": "# What Is Spec-Driven Development? The Spec as Source of Truth\n\nThe spec as source of truth, not a side document.\n\nSpec-Driven Development is one of those ideas that software engineers have reached for before and then set aside when the effort stopped paying.\n\nWhat changed in 2025 is that AI coding agents arrived and made the absence of explicit intent expensive. Prompts are ephemeral. Agent sessions reset. Code changes but the reasoning behind it disappears. The spec is the artifact that stops that from happening.\n\n## The Spec Is Becoming the Source of Truth\n\nFor most of software development history, the spec was either a temporary planning artifact or an afterthought. Requirements lived in tickets, design decisions lived in chat threads, and the code was the ground truth. Documentation described what existed after the fact.\n\nSpec-Driven Development inverts that relationship. The specification becomes the primary artifact. Code is what gets generated or verified against the spec, not the other way around.\n\nThis is not a new idea. Formal methods, design-by-contract, and BDD all contain versions of it. What is new is the practical motivation: AI coding agents need explicit, durable context to produce correct and consistent output. Prompts are too ephemeral. The spec is the only artifact that can carry intent across agent sessions, across team members, and across time.\n\n## What Spec-Driven Development Actually Means\n\nSpec-Driven Development, usually shortened to SDD, is a workflow where a versioned specification guides or generates implementation. The specification is written and reviewed before the agent writes code. It captures:\n\n**What to build**– user problem, goals, and non-goals** What correct behavior looks like**– acceptance criteria, edge cases, error states** How to build it**– architecture decisions, data model, API contracts, security constraints** How to verify it**– test strategy, validation rules, traceability back to requirements\n\nThe spec is not a one-time document. It is updated when reality differs from the design. When the agent discovers something during implementation that the spec got wrong, the spec is corrected before continuing. The spec stays honest because it is treated like code.\n\nRecent academic work formalizes this framing: researchers describe SDD as treating specifications as the source of truth and code as generated or verified against them. The practical interpretation is that the spec is the reviewed, durable record of intent that any human or AI tool can read and trust.\n\nThree terms capture different points on the spec-use spectrum:\n\n**Spec-first** means writing the full specification before any implementation begins. This\nis the strictest interpretation and the one closest to waterfall if not done carefully.\n\n**Spec-anchored** means keeping a specification in sync with implementation throughout the\nfeature lifecycle. The spec is updated as decisions change. This is the most practical\nversion for most teams.\n\n**Spec-as-source** means generating or validating implementation from the spec, either\nthrough AI agents or through tooling that checks code against spec constraints. This is the\ndirection tools like GitHub Spec Kit and Kiro are moving toward.\n\n## Why SDD Matters Now\n\nThe honest answer is that SDD is not compelling for a solo developer building a one-day script. The overhead is not worth it.\n\nSDD becomes valuable when three conditions are present: the feature is large enough to span multiple sessions, the agent needs to make decisions that affect the architecture, and the work will be reviewed or continued by someone else.\n\nAll three conditions are increasingly common with AI-assisted development.\n\n**LLMs need context, not just prompts.** A model that receives a vague prompt makes vague\ndecisions. A model that receives a reviewed specification with explicit constraints, non-goals,\nand acceptance criteria makes better decisions and is easier to course-correct when it drifts.\nThis connects to how [retrieval and representation](https://www.glukhov.org/knowledge-management/foundations/retrieval-vs-representation/) work: giving an agent a versioned spec is a form of structured retrieval of project intent.\n\n**Code generation is cheap; deciding what to build is still hard.** The bottleneck in AI-assisted\ndevelopment is no longer typing – it is knowing what to build and how to constrain the\nagent. SDD shifts the effort to where it matters: specifying intent clearly before generation\nbegins.\n\n**Prompts are ephemeral.** The agent does not remember what you told it in the last session.\nA versioned specification stored in the repository does. Every new session can read the same\nspec and implement against the same intent without re-establishing context from scratch.\n\n** Vibe coding works until it does not.** For prototypes and throwaway work, ad-hoc prompting is\nfaster and appropriate. As soon as a feature requires security constraints, multi-file\narchitecture decisions, or a team handoff, the absence of a spec becomes the main source of\ndrift and defects. See the comparison in\n\n[SDD vs Vibe Coding](https://www.glukhov.org/ai-devtools/vibe-coding/spec-driven-development-vs-vibe-coding/)for when each approach applies.\n\n## Core Artifacts\n\nA practical SDD workflow produces four main artifacts. Each one reduces a specific kind of ambiguity before it reaches the agent.\n\n**Requirements specification.** The problem statement, the users affected, the goals, the\nexplicit non-goals, and the acceptance criteria. Non-goals are as important as goals – they\ntell the agent what not to build and prevent scope creep. Acceptance criteria are precise\nenough that each one maps to at least one test.\n\n**Design specification.** The architectural decisions relevant to this feature: affected\nmodules, data model changes, API contracts, migrations, security constraints, observability\nrequirements, and known failure modes. This is not a full system design document – it is the\nsubset of architecture decisions needed to implement this feature correctly.\n\n**Task plan.** A sequence of small implementation tasks, each with explicit dependencies,\nexpected file changes, and validation criteria. Tasks are small enough to implement in a\nsingle agent session and verify with a focused diff. Each task has a human review checkpoint.\n\n**Traceability record.** A mapping from acceptance criteria to tests, from design decisions\nto affected files, and from tasks to commits. This is what separates SDD from documentation\nthat becomes stale: traceability makes it possible to verify that the spec was actually\nimplemented, not just written.\n\nThese artifacts do not have to be heavyweight. A simple feature might produce a single two-page markdown document covering all four areas. The format matters less than the habit of writing intent down before implementation begins.\n\n## How SDD Differs from Documentation\n\nThe most common confusion is treating SDD artifacts as documentation. They are not documentation in the conventional sense.\n\n**Documentation describes.** It tells you what the system does, how to use it, and what\nit contains. It is written after the fact and updated when the system changes.\n\n**Specs constrain.** A spec tells the agent what it is allowed to build and what it is\nnot allowed to do. It is authoritative before implementation begins. It is validated after\nimplementation completes. A spec that describes what was actually built – rather than\nconstraining what should be built – has already failed its purpose.\n\n**Executable specs guide generation and validation.** The best SDD specs are close enough\nto machine-readable that an agent can implement against them and a test suite can verify\nthem. Acceptance criteria written as “the endpoint must reject unauthenticated requests with\na 401 response” is an executable spec; “the endpoint is secure” is documentation.\n\n[Decision Records](https://www.glukhov.org/app-architecture/documentation/decision-records-ai-driven-development/) – ADRs, PDRs, and DDRs – are complementary to SDD artifacts but serve a different\npurpose. Decision records capture why a choice was made and what was rejected. SDD\nspecifications capture what to build and how to verify it. Both belong in the repository.\nTogether they give AI agents the full picture: the current intent and the reasoning behind it.\n\n## How SDD Differs from TDD\n\nTest-Driven Development and Spec-Driven Development are often confused because both produce explicit artifacts before code exists. The difference is the starting point.\n\n**TDD starts with tests.** You write a failing test that describes the behavior you want,\nthen write the minimum code to make it pass. TDD is a feedback loop at the unit level. It\nproduces good tests but does not answer the question of whether you are building the right\nthing.\n\n**SDD starts with intent.** Before tests exist, before the architecture is decided, the\nspec answers: who has this problem, what does correct behavior look like, what is explicitly\nout of scope. The spec then informs what tests to write, which is why good SDD and good TDD\nare complementary rather than competing.\n\nA practical way to think about it: SDD drives TDD. The acceptance criteria in the spec become the test scenarios. The design spec identifies the integration boundaries that need contract tests. The task plan identifies which unit behaviors need test coverage before the agent implements them.\n\n## How SDD Differs from BDD\n\nBehavior-Driven Development uses natural-language scenarios – typically in Gherkin format – to describe expected behavior from the user’s perspective. These scenarios bridge the gap between business intent and technical implementation.\n\nSDD is broader. It includes behavior descriptions (which can use BDD-style language or plain prose) but also covers architecture decisions, data models, security constraints, task planning, and traceability. BDD can be a useful format for writing acceptance criteria inside an SDD requirements spec. The spec is the container; BDD scenarios are one way to write what goes inside it.\n\nThe distinction matters in practice: BDD tooling focuses on making scenarios executable. SDD practice focuses on making intent durable – across tools, across sessions, and across team members.\n\n## How SDD Differs from Formal Methods\n\nFormal methods use mathematical notation and automated verification to prove properties of software systems. They are extremely rigorous and extremely expensive for most production development contexts.\n\nSDD does not require formal notation. A markdown file with acceptance criteria and architecture decisions is a specification. It constrains without being mathematically formal. The level of rigor scales with the stakes: a spec for a billing service should be more precise and more carefully reviewed than a spec for a documentation page.\n\nThe relationship is a spectrum:\n\n- Informal prose spec (minimum viable SDD)\n- Structured markdown with acceptance criteria and non-goals\n- Machine-readable spec with schema validation\n- Contract tests derived directly from the spec\n- Formal spec with automated proof\n\nMost teams operate in the middle of that spectrum. The goal is not mathematical rigor – it is making intent explicit enough that an AI agent can implement against it and a human reviewer can verify the result.\n\n## Benefits of Spec-Driven Development\n\n**Less intent drift.** The spec is the reference. When the agent drifts – and it will – the\nreviewer has something to compare the implementation against. Without a spec, drift is\ninvisible until something breaks.\n\n**Better AI outputs.** Agents given explicit constraints, non-goals, and acceptance criteria\nproduce implementations that are closer to what was intended and easier to correct when they\nmiss. Context quality directly determines output quality.\n\n**Easier review.** A pull request attached to a spec is easier to review than a pull request\nthat requires the reviewer to reconstruct the intent from the code. The spec is the review\nchecklist.\n\n**Team alignment.** When multiple people or agents are working on the same feature, the spec\nis the shared contract. Without it, each contributor optimizes locally and the pieces may\nnot fit.\n\n**Better test planning.** Acceptance criteria in the spec map directly to test cases. Test\ncoverage becomes a spec coverage question: is every acceptance criterion covered by at least\none test?\n\n**Durable handoff.** When a feature changes hands – between engineers, between agent sessions,\nbetween sprints – the spec is the handoff artifact. It captures what was decided, what was\nout of scope, and what remains to be validated.\n\n## Costs of Spec-Driven Development\n\n**Upfront effort.** Writing a good spec before writing any code takes time. For small\nfeatures, this overhead is real and sometimes not worth it.\n\n**False confidence.** A spec that exists but is not validated against the implementation\ngives a false sense of correctness. Stale specs are sometimes worse than no spec: they\nmislead reviewers and agents that read them.\n\n**Stale specs.** Specs drift when the team treats them as planning artifacts rather than\nliving documents. Updating the spec when implementation differs from design is not optional\n– it is what separates SDD from documentation that accumulates and rots.\n\n**Generated bureaucracy.** AI agents can generate exhaustive task lists and verbose\nspecifications quickly. A 200-task spec generated in thirty seconds is not a useful spec –\nit is a bureaucracy generator. Good SDD requires judgment about what to specify and what to\nleave implicit.\n\n**Tool lock-in.** Some SDD tools are opinionated about format, file structure, and workflow.\nA spec written in a proprietary format is harder to carry across tools than a markdown file\nwith clear headers and acceptance criteria.\n\n## Conclusion\n\nSpec-Driven Development is not a new methodology. It is an old discipline becoming practical again because the cost of implicit intent is now visible in AI-generated code.\n\nThe discipline is simple: write down what you intend to build, reviewed and versioned, before the agent builds it. Keep that record honest by updating it when reality differs. Use it as the reference for review, testing, and handoff.\n\nThe spec is not magic. A spec that is not validated becomes the most expensive kind of documentation: one that misleads confidently. Good SDD is the practice of keeping specs honest – small enough to maintain, precise enough to constrain, and durable enough to outlast any single agent session.\n\nSDD sits at the intersection of documentation practice, testing architecture, and code design –\nall covered in the [App Architecture in Production](https://www.glukhov.org/app-architecture/) cluster alongside decision records, API design, and data access patterns.\n\n## Useful Links\n\n[Decision Records for AI-Driven Software Development](https://www.glukhov.org/app-architecture/documentation/decision-records-ai-driven-development/)– ADRs, PDRs, and DDRs that complement SDD specs by capturing why decisions were made[Spec-Driven Development vs Vibe Coding: Waterfall?](https://www.glukhov.org/ai-devtools/vibe-coding/spec-driven-development-vs-vibe-coding/)– when to add specs and when to keep prompting freely[What is Vibe Coding – Meaning, Tools, Benefits, and Risks](https://www.glukhov.org/ai-devtools/vibe-coding/)– the vibe coding cluster pillar[App Architecture in Production](https://www.glukhov.org/app-architecture/)– the cluster home for architecture, documentation, testing, and integration patterns[Unit Testing in Go: Structure and Best Practices](https://www.glukhov.org/app-architecture/testing-architecture/unit-testing-in-go/)– turning SDD acceptance criteria into executable tests[Unit Testing in Python: Complete Guide](https://www.glukhov.org/app-architecture/testing-architecture/unit-testing-in-python/)– test-writing practices that map to SDD acceptance criteria[Python Design Patterns for Clean Architecture](https://www.glukhov.org/app-architecture/code-architecture/python-design-patterns-for-clean-architecture/)– code structure practices that SDD helps preserve[Retrieval vs Representation in Knowledge Management](https://www.glukhov.org/knowledge-management/foundations/retrieval-vs-representation/)– how explicit specs relate to AI context and retrieval[GitHub Spec Kit documentation](https://github.github.io/spec-kit/)– a portable open-source SDD toolkit[Martin Fowler on Spec-Driven Development tools](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)– careful analysis of Kiro, Spec Kit, and Tessl", "url": "https://wpnews.pro/news/what-is-spec-driven-development-the-spec-as-source-of-truth", "canonical_source": "https://www.glukhov.org/app-architecture/documentation/what-is-spec-driven-development/", "published_at": "2026-06-29 09:54:57+00:00", "updated_at": "2026-06-29 10:32:42.410003+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "large-language-models", "ai-tools"], "entities": ["GitHub Spec Kit", "Kiro"], "alternates": {"html": "https://wpnews.pro/news/what-is-spec-driven-development-the-spec-as-source-of-truth", "markdown": "https://wpnews.pro/news/what-is-spec-driven-development-the-spec-as-source-of-truth.md", "text": "https://wpnews.pro/news/what-is-spec-driven-development-the-spec-as-source-of-truth.txt", "jsonld": "https://wpnews.pro/news/what-is-spec-driven-development-the-spec-as-source-of-truth.jsonld"}}