Spec Driven Development: What It Is, How It Works, and Where It Fails
Last updated:26 October 2026
AI coding agents can now turn a short prompt into a working feature in minutes. Whether it is the right feature, built the right way, is a different question.
A January 2026 SonarSource survey of more than 1,100 developers found that 96% don’t fully trust that AI-generated code is functionally correct, and only 48% always check it before committing.
That is why more engineers are adopting spec-driven development: agreeing in writing on what to build before any code exists. The approach is older than AI, works with or without it, and goes further than writing documentation first. AI just made the cost of vague requirements much harder to ignore.
In our new article, we cover what spec-driven development means, how it works in practice, where it delivers real value, and where it gets misapplied or expected to do too much. We also share what we learned using it on a real client project.
Key Takeaways
- Spec-driven development (SDD) makes a structured specification, written before any code, the source of truth for implementation, tests, and documentation.
- SDD is older than AI. It borrows from design by contract and test-driven development, and coding agents made it newly practical.
- A useful spec covers outcomes, scope boundaries, constraints, prior architectural decisions, a task breakdown, and verification criteria.
- The value is real when a spec limits what an agent can get wrong, aligns parallel work, and records intent.
- SDD breaks down through over-specification, spec drift, heavy specs on throwaway work, and specs that only one person reads. The spec’s weight should match the problem.
What Is Spec-Driven Development?
Spec-driven development is a software development methodology where a structured specification, written before any code, serves as the authoritative source of truth. Implementation, testing, and documentation are all derived from that spec. Any change in behavior starts with a change to the spec.
That is the spec-driven development definition we use here, and “structured” carries most of the weight. In traditional development, requirements live in tickets, meeting notes, and chat threads. SDD pulls them into a reviewed spec, precise enough for a developer or coding agents to act on without guessing.
What does a spec look like?
Practitioners call a spec a behavior-oriented artifact. It states what the software does in specific situations, including edge cases, and how anyone can check it. Here is a small example:
## Feature: user registration endpoint
Why: users share accounts today; we need per-user settings.
Scope: POST /users only.
Out of scope: social login, password reset, email verification.
Constraints: reuse the existing auth service. No new tables. No new dependencies.
Behavior:
- Invalid email → 400. Duplicate email → 409.
- Empty body → 400. Payload over 1 MB → 413. Unicode names are stored unchanged.
Verify:
- A unit test for each rule above passes.
- p95 response time stays under 200 ms in the load test.
Where does SDD come from?
The spec-driven development methodology predates AI by decades. Formal methods, executable specifications, and design by contract all put expected behavior ahead of working code. Test-driven development turned it into failing tests, and behavior-driven development into readable natural-language scenarios.
What changed is the reader. Large Language Models (LLMs) now generate code from natural language, so a written spec can drive an agent directly. Spec-driven development AI workflows took off in 2025, when GitHub’s Spec Kit and AWS Kiro made the spec the primary artifact.
Is SDD just documentation first or Waterfall?
SDD goes further than documentation first, and the difference lies in what the document does. Documentation describes a system after it exists. A spec is written to define behavior before the system exists.
The implementation must match the spec, and the spec and its plan are executable artifacts that an agent can act on directly.
SDD also differs from Waterfall, which is a common objection. Waterfall fixes requirements for the whole project up front. A spec covers only the next piece of work, and the loop repeats: build a task, review the code, refine the spec, and continue.
Spec-first, spec-anchored, or spec-as-source?
AI-assisted delivery expert Birgitta Böckeler mapped the levels of commitment in an October 2025 review of SDD tools:
- Spec-first. A spec guides the initial implementation of one task.
- Spec-anchored. The spec survives the task and evolves with the feature.
- Spec-as-source. People edit only the spec, and the code is regenerated from it.
In her review, Kiro and Spec Kit work as spec-first in practice, while Tessl aims for spec-anchored and even explores spec-as-source.
No spec-driven development guide can pick the right level in advance, because it depends on how long the feature will live and how many people will touch it.
How Does Spec Driven Development Work?
Spec-driven development works as a loop: discuss, specify, break down, implement, verify, and version. People approve the spec before work starts, and the structured workflow stays the same across tools.
The core spec elements
A well-formed spec answers these questions before anyone starts writing code:
- Outcomes. The spec says what changes for the user when the feature ships, tied to a user story or business result.
- Scope boundaries. The spec states what is in and what is explicitly out, so agents skip the extras.
- Constraints. The spec lists the tech stack, performance limits, security rules, and architectural constraints the feature must respect.
- Prior decisions. The spec records technical decisions already made, so nobody reopens them mid-build.
- Task breakdown. A technical plan splits the work into small steps with clear commit boundaries.
- Verification criteria. Acceptance criteria define what a reviewer or an automated test can check objectively.
Implementation details belong outside the outcome section, and technical details belong in the plan. Mixing them makes a spec hard to review.
The spec lifecycle
Discuss → Specify → Break Down → Implement → Verify → Version
- Discussion. A person and an agent talk through the task first. The agent asks questions, surfaces gray areas, and records defaults for edge cases the ticket does not cover, plus what is deliberately left to the agent’s judgment.
- Spec authoring. An agent drafts the spec from the discussion, a ticket, or a call transcript. A person answers its questions and approves the decisions. That approval is one of the phase gates: nothing gets built until intent is agreed.
- Task breakdown. The spec becomes an implementation plan of numbered tasks, each small enough to review alone.
- Implementation. A developer or one of the AI coding agents works task by task against the same spec, so all code generated traces back to it.
- Verification. Reviewers and tests validate AI-generated output against the acceptance criteria. Plausible-looking code earns no credit on its own.
- Versioning. When behavior changes, the spec changes first. Specs live in version control as markdown files, next to the code or, for multi-repo systems, in a planning repository beside it.
The last step is the easiest one to skip, which leads straight to the pitfalls below.
Spec vs. other project documents
A spec is a contract for one feature. It also differs from documents teams already write:
- Product requirements document (PRD). A PRD tells stakeholders what to build and why.
- Technical design. A technical design tells engineers how to build it and which trade-offs were made.
- AI spec. An AI spec tells an agent what to execute: the context, the constraints, what is out of scope, and tasks with a check for each.
Once approved, an AI spec is executed as written, and any debate belongs before approval.
A context document, sometimes called a memory bank, is different again. It holds general knowledge about the codebase: architecture notes, coding conventions, security rules, and product background.
Context engineering is the practice of curating that knowledge, per repository and across technical stacks, so every agent session starts informed. Context documents tell an agent how this codebase works. The spec tells it what to build right now, and how to know when it is done.
The two work best in separate files. Feature detail that leaks into global context becomes noise in every future session.
What Value Does Spec Driven Development Actually Deliver?
Spec-driven development catches architectural drift before it reaches production, narrows what an AI agent can get wrong, and leaves a reviewable record of intent.
Each benefit depends on the spec staying specific and current.
For engineering teams
The biggest gain is earlier disagreement. Misunderstandings surface during review of a short document, while they are still cheap to fix.
A spec catches architectural drift too. If a plan adds a new table where the architecture says to reuse a service, a reviewer spots it long before it becomes technical debt.
Parallel work gets easier as well. With clear task boundaries and shared acceptance criteria, two engineers or two agents can build separate parts without colliding.
In practice, several people can work in parallel on separate PRDs or on different phases of one roadmap. On one of our proofs of concept, an engineer and a business analyst split the phases between them. The analyst picked up her phase from an onboarding file that our SDD tooling generated.
Discussion and planning of the next phase can run while the previous phase is being executed. This works when each PRD and roadmap has one owner who decides how the work is split and numbered. Without that owner, two people can create conflicting pieces of the same plan.
For AI-assisted workflows
In AI-assisted development, a spec shrinks the space where an agent can hallucinate. An agent asked to “add registration” has to guess the tech stack, the error format, and every edge case. An agent given a structured specification has far fewer blanks to fill in.
Specs also fight context rot. In a long session, an agent gradually loses track of the goal and starts breaking what already works.
A spec splits the work into phases, each executor agent starts with a fresh context, and the state lives in files. A session can stop or hit a usage limit, and the next one resumes from those files with nothing lost.
A spec also targets a bigger bottleneck than typing speed. Ming Wu, Atlassian's head of engineering for Dev AI, told TechTarget in July 2026 that coding takes only about 15% to 16% of the time developers spend across the software development lifecycle. He added that productivity gains from coding agents have plateaued at 10% to 15%. Faster typing cannot fix the rest of that time, but clearer intent can help.
Written specs support security, too. If the feature itself uses Large Language Models, documented access rules and data boundaries give an AI pentesting service a clear baseline to test against.
For regulated or compliance-sensitive contexts
In regulated industries such as HealthTech and FinTech, auditors ask what each piece of software functionality was supposed to do and who approved it. A versioned spec answers both. It records the original intent, the approval, and every change since.
A spec will not replace compliance evidence on its own. It does make traceability cheap, because each test and pull request can point back to a line in the spec. It also carries specification authority: disputes about intended behavior get settled by reading it.
In our delivery at TechMagic, regression tests come from the ticket’s acceptance criteria, and API requests are logged. When agents run checks against a live environment, every write needs a recorded approval.
SDD vs. ad-hoc AI prompting
Here is how the two approaches compare:
Where Does Spec-Driven Development Break Down?
Spec-driven development breaks down when the spec gets too heavy too early, falls out of date, outweighs the exploratory work it supports, or is read by only one person. Each failure has a structural cause, and none of them comes down to careless engineers.
Over-specification early in the project
A detailed specification written before anyone understands the problem freezes guesses into requirements. The agent implements those guesses faithfully, and the project pays twice.
Review load grows as well. Testing SDD tools on small tasks, Böckeler wrote that she would “rather review code than all these markdown files.” When a spec is longer than the change it describes, the process works against the people using it.
Legacy systems add a trap: the spec must start from how the existing code really behaves. A good spec matches the level of certainty that actually exists and marks open questions as open.
Getting this balance wrong is expensive: Gartner predicts that over 40% of agentic AI projects will be canceled by the end of 2027, citing escalating costs, unclear business value, and inadequate risk controls. A spec process that adds cost without adding clarity pushes a project toward the first two.
Spec drift and maintenance neglect
Spec drift happens when the implementation changes and the spec does not. A bug fix alters behavior, a reviewer approves a shortcut, and three weeks later the spec describes a system that no longer exists.
Updating the spec is a separate step with no immediate reward, so it loses to the next ticket. Then agents read the wrong spec and produce wrong code with full confidence.
The fix is to make the spec part of every change: any change that alters behavior also updates the spec, and review checks both. Static documents drift quietly, while specs reviewed alongside the code stay accurate.
Spec weight in exploratory work
SDD needs the next step to be clear, while the rest of the product can stay open. The real risk in exploratory work is a spec that is too heavy for the task.
For a throwaway spike, a spec is pure overhead that slows the feedback loop. On one small experiment, an agent without a spec produced a first working build in about 10 minutes, while the spec-driven run took about an hour.
For an MVP with uncertain requirements, a spec scoped to the next phase works well. We built an internal booking app this way in about three and a half days.
Team adoption failure patterns
A spec needs one owner to coordinate it. SDD fails quietly when that owner is also its only reader and everyone else works around it, because the spec turns into a private plan and stops reflecting shared decisions.
Other patterns show up often:
- Specs as paperwork. A template gets filled in to pass a gate, and nobody reads it again.
- Too abstract for agents. "Make onboarding smooth" gives coding assistants nothing to act on. Structured specs state inputs, outputs, and limits.
- One workflow for every task. A two-line change gets the same heavy process as a new service, so people abandon it.
- No amendment path. If changing a spec mid-build needs a full review cycle, people change the code and skip the spec.
Adoption works when everyone reviews specs, the workflow scales with task size, and amendments are cheap.
We Tried Spec-Driven Development on a Real Client Project. We’re Sharing Our Insights
We used spec-driven development to fix a production AI module in a mature enterprise SaaS product, and the work took three working days. Here is how it ran, what the spec looked like, and what we would repeat.
The project context
The product is a mature enterprise SaaS platform that has been on the market for years. It spans more than a dozen repositories and serves live customers.
A recently released module, an AI assistant that plans configuration cleanup, analyzes the impact of a change, assesses architectural risk, and builds a backlog.
After the release, QA found defects in how these steps passed results to each other. The Product Owner set the goal of fixing the chain before a wider rollout.
Step zero: a system map
Before any feature work, agents mapped the existing codebase. The map covered the stack, architecture, integrations, conventions, and known concerns of each repository. Without that map, an agent rediscovers the system from scratch every time and proposes adding things that already exist.
The planning repository and the workflow
The framework we use, GSD, assumes a single repository, and this product has many. So the specs live in a separate planning repository next to the code repositories, with 17 repositories registered in it. The code repositories only see branches, commits, and pull requests.
In GSD, the cycle runs in four steps:
Discuss → Plan → Execute → Verify
A separate agent checked each plan. The first phase went through the full cycle, and the next two went through a lighter one with a single plan each.
People keep the decisions that matter. The developer approves the agent’s implementation plan before any code is written, and merges, package releases, and ticket transitions stay with people.
Agents speed up production, so verification becomes the bottleneck. Review starts with agents, then a developer reads the change and owns the merge, with a second reviewer on high-risk changes. QA tests on an environment, and the Product Owner accepts the business result.
The spec for each phase
Each phase had its own set of spec files:
- Context file. A context file of about 100 to 120 lines recorded the decisions made.
- Plan. A plan of 234 to 453 lines held acceptance criteria that the agent checks itself, such as grep checks, tests, and the failing-test count.
- Summary and verification report. Both files closed the phase once the work was done.
The context file and the plan came out of a discussion of about 50 minutes with the tech lead, who approved the decisions.
The most valuable part of the context file was the defaults for edge cases the ticket did not cover. For example, when the impact of a change is uncertain, the item stays in the backlog. A missed dependency can break a customer’s live environment, while an extra backlog item is cheap.
Legacy code also needed an honest baseline. Part of the local test suite was already failing before any change: 76 of 280 tests. So the bar was a stable failure count, and it held, with 76 failures before and after, plus 26 new tests.
The biggest gains
The first gain was alignment with QA, and it ended the “bug or feature?” arguments.
Expert view: What changed when acceptance criteria came straight from QA’s tickets?
“The expected results in QA’s tickets became our acceptance criteria word for word. We settled the disputed cases once, in the spec, and QA then checked exactly what was written there.” – Ihor S., Technical Lead at TechMagic
The second gain came halfway through. The discussion for one phase showed that most of the work was already done, because a colleague had recently changed that part of the UI. We rewrote the spec before planning, and a cross-repository feature shrank to a single frontend revert.
Without the spec, the agent would have rewritten the backend.
The cheapest moment to amend a spec is before the plan, long before any code exists.
The hard parts
The full cycle is expensive: one evening session used up a whole five-hour usage window. The agent also opened pull requests against the wrong branch several times, until the rule was written into the repository’s instructions.
Checks on a live environment stayed manual. The verifier agent listed what it could not check and why.
Fixes like that branch rule come from a regular review. Every task leaves a trail: the spec, the plan, a summary, and the agents’ run history. That lets us review the work regularly from recorded data.
The review looks at what blocked development, where most of the time and tokens went, which agent mistakes repeated, and which skills were missing. The fixes become changes to rules and skills, shipped through a pull request like any other code.
Results and advice for a first try
Three phases, seven requirements, and four pull requests took three working days, with no change in the number of failing tests.
Expert advice for teams trying SDD on an existing product:
“In an existing product, start with a map of the system and a test baseline, and write checks into the spec that the agent can run itself, instead of ‘it should work’.”
Need Expert Help With Spec Driven Development?
TechMagic helps engineering teams bring AI agents into the development process without losing control of the architecture. That includes the spec workflow, review gates, and context documents that make agents useful on existing codebases.
Spec-Driven Development: Summary and What’s Next
Spec-driven development makes a structured, reviewed spec the source of truth for what gets built. Its value is real where specs constrain agents, align people, and record intent. It is misapplied when specs are heavy, stale, forced onto throwaway experiments, or read by only one person.
For software delivery teams, spec-driven development with AI comes down to one habit: agreeing on intent before code.
One takeaway for each role:
- Engineers. Acceptance criteria come before the prompt. If nobody can say how to check the result, an agent cannot build it reliably.
- Tech leads. The spec should scale with the task, and amending it should cost less than ignoring it.
- Engineering managers. The useful signal is whether specs change decisions in review. A spec nobody reads is pure overhead.
Where is this heading?
AI code assistants are becoming the default. Gartner predicts that 90% of enterprise software engineers will use AI code assistants by 2028, up from less than 14% in early 2024. More generated code needs a reference to check it against.
Specs will reach beyond engineering. Deloitte found that 74% of leaders expect nearly half of their business processes to be redesigned or rebuilt around AI agents within four years. Only 5% say their processes are highly prepared. Written intent is part of that preparation.
Spec tooling will get lighter. Spec-driven development tools such as Spec Kit and Kiro package AI spec-driven development into the agent. Most tools still push every task through one opinionated workflow, as Böckeler noted. Some, like GSD, the framework from our project, already offer a quick mode for small tasks and a way to insert new phases mid-project, and we expect the rest to follow.
FAQ
Spec-driven development is a software engineering methodology where a structured specification, written before any code, is the source of truth for implementation, tests, and documentation. A practical spec-driven development definition adds one rule: any change in behavior starts with a change to the spec.
Spec driven development (SDD) defines what a feature should do and why, in a structured specification that guides the whole build. Test driven development (TDD) writes a failing unit test before each small piece of code. SDD and TDD work well together, because SDD acceptance criteria often become the tests that TDD drives.
Spec driven development (SDD) and behavior driven development (BDD) both describe expected behavior before code is written. BDD focuses on natural language scenarios that business people and testers share. SDD covers more ground, adding scope, constraints, architectural decisions, and a task plan that a developer or an AI coding agent executes.
Spec driven development (SDD) is a poor fit for throwaway spikes and early discovery, where the goal is to learn what to build. SDD also adds little to tiny changes that one engineer can finish and review in minutes. Teams get the most from SDD on features with several implementers, AI coding agents, or compliance requirements.
Spec driven development (SDD) prevents architectural drift, scope creep, misaligned assumptions between engineers, and AI generated code that solves the wrong problem. SDD catches these issues at spec review, before implementation starts. SDD cannot prevent errors in the spec itself, so specs need review and upkeep.
TechMagic uses spec-driven development on existing products and new builds alike. On a mature enterprise SaaS product, TechMagic engineers ran each phase through discussion, planning, execution, and verification with AI agents, keeping the specs in a separate planning repository. The team delivered seven requirements in three working days with no change in the number of failing tests.
