Spec driven development is not a new name for writing requirements first. The difference is what happens to the document afterward: the specification stays in the loop as the artifact an AI coding agent works from, rather than context a developer reads once and abandons.
That distinction matters more with agents than it did with people. A developer who half-understands a ticket asks a question. An agent fills the gap silently and confidently, and you find out during review — or later.
This page covers the general method, where it earns its cost, and where it does not. Product details were verified against official documentation on 2026-08-18.
What Spec Driven Development Changes
The clearest framing comes from GitHub's Spec Kit, which describes SDD as making specifications executable rather than merely guiding implementation, with intent defined before the "how," refinement across multiple steps instead of one-shot generation from prompts, and explicit guardrails.
Three things follow from that, and they are worth separating because teams routinely conflate them.
The methodology is the sequence: intent, then structure, then code, with a reviewable artifact at each step.
The tool implementation is whatever runs it. Spec Kit is one; Kiro is another; a team can run the same sequence with Markdown files and no tooling at all.
The governance is who owns the artifacts once they exist, and what happens when requirements change. This is the part no tool decides for you — a point Spec Kit's own documentation makes explicitly.
Keeping these separate saves an argument later. An adoption that stalls is often described as a methodology problem when the unresolved question is governance — who owns the artifact after it exists.
One more boundary: there is no single industry definition of SDD. Spec Kit's docs cite a three-level framing — spec-first, where the spec is discarded after coding; spec-anchored, where it is kept for future changes; and spec-as-source, where implementation artifacts are regenerated from it. When someone says "we do SDD," ask which of those they mean.
The Spec-to-Code Workflow
Requirements, Design, Tasks, and Implementation
Spec Kit ships the core process as Spec → Plan → Tasks → Implement, where each phase produces a Markdown artifact that feeds the next, giving the agent structured context instead of ad-hoc prompts. The docs show the corresponding commands in /speckit.* form — specify, plan, tasks, implement — while noting that the exact invocation varies by agent; some use $speckit-* or a skill-prefixed form instead.
The phases map to four different questions, and the split is the useful part:
- Spec — what should be true when this is done, in behavior, not implementation
- Plan — how the system will change: components, data, boundaries
- Tasks — the work breakdown, in units small enough to review individually
- Implement — code, with the previous three as context
Most teams already do all four. What changes is that each one becomes a file rather than a shared assumption, and the agent reads the file.
The practical consequence is narrower than the marketing suggests. You are not eliminating ambiguity; you are relocating it. Ambiguity that used to surface in code review now surfaces in spec review, where it is cheaper to resolve and where non-engineers can participate.
Review Checkpoints and Approval Gates
The gates are what make the sequence more than documentation. Two are worth building into any adoption.
Before implementation, run a cross-artifact check. Spec Kit provides /speckit.analyze for exactly this — catching gaps between spec, plan, and tasks before implementation resumes. A spec that no longer agrees with its own task list will produce code that agrees with neither.
After implementation, review the code and the artifact diffs together. If the agent changed behavior that the spec does not describe, you want to see that in the same pass, not discover it three features later.
Teams that need harder enforcement can attach compliance gates at the pipeline level — Spec Kit's ecosystem includes community extensions such as CI Guard and Architecture Guard for that purpose. Whether you need them is a governance question, not a tooling one.
For how review gates interact with agent-generated pull requests specifically, automated review works better as queue triage than as an approval bot.
Where SDD Helps AI Coding Teams
Brownfield Changes and Large Codebases
Greenfield is where SDD demos well and where it matters least — a small new project has few unstated assumptions to violate.
Brownfield is the opposite. The constraints that make a change hard are usually undocumented: a boundary someone drew for a reason nobody wrote down, a workaround that must stay. Spec Kit's own phase model lists iterative enhancement and modernization of legacy systems as a distinct mode from greenfield generation, and the artifact that pays for itself in that mode is the plan, not the spec — because it is where those constraints get written down for the first time.
A useful rule for existing repositories: the spec describes the change, and the plan describes what must not change. The second half is the part agents get wrong.
Multi-Agent Coordination and Handoffs
When more than one agent works on the same repository, the specification becomes the shared reference. Without it, each agent reconstructs intent from the code it happens to read, and two reasonable reconstructions diverge.
Tasks are the coordination unit here. A task list that is decomposed and explicitly scoped can be distributed; a spec cannot. This is also where the review burden concentrates, because parallel work produces parallel diffs, and a human still has to hold the whole picture. The ownership question — who is accountable for an agentic workflow once it runs across a team — arrives faster with multiple agents than most teams expect.
Tooling matters less here than the scoping discipline. Two agents with well-bounded tasks coordinate through files without much friction. Two agents with overlapping tasks are more likely to produce integration conflicts, even where workspace isolation keeps them from editing the same files during execution — the collision surfaces at merge instead.
Common Failure Modes and Trade-Offs
Stale Specs and Implementation Drift
This failure mode is worth being precise about, because the cause is usually mistaken for a tooling problem.
Spec Kit is explicit that it does not prescribe how teams preserve or mutate the artifacts after requirements change, and it names three models without defaulting to any: flow-back, where any artifact can be edited first and the set is reconciled afterward; flow-forward, where completed feature directories are immutable and new requirements create new directories; and living spec, where the spec is the contract and downstream artifacts are regenerated from it.
Each carries a documented risk. Flow-back risks silent divergence between artifacts. Flow-forward risks duplication across directories. Living spec risks losing implementation rationale when derived artifacts are replaced.
The failure is not picking the wrong model. It is picking none, and discovering months later that half the team edits tasks directly while the other half treats the spec as truth. Write the choice down — the documentation suggests recording it in the project constitution or onboarding notes.
Over-Specification and Review Overhead
The cost of SDD is real and lands on the same people every time: whoever reviews specs.
Specifying a two-line config change through four phases is worse than editing the file. Specifying a payment flow through four phases is cheaper than debugging it in production. The judgment is about blast radius and how many people need to agree, not about ceremony.
Watch for two symptoms. Specs that restate the plan in different words mean the phases are not doing separate jobs. Specs that describe implementation rather than behavior mean the spec is a plan with a different filename.
And a claim worth resisting: the evidence that SDD generally makes teams faster is limited and not yet generalizable. Published material at this point runs to individual case reports rather than controlled comparisons, and the vendor documentation does not make a speed claim either. What SDD offers is a structure where intent is reviewable before code exists. Whether that trade is worth it depends on the cost of your defects, not on someone else's case study.
How to Adopt SDD in an Existing Repository
Start With a Bounded Pilot
Pick one feature with a clear boundary and a real reviewer. Not a spike, not the biggest refactor on the backlog.
Run the full sequence once, including the checks, and keep the artifacts even if the feature ships imperfectly. The output you actually want from a pilot is a calibrated sense of how long spec review takes on your team, which is the number that determines whether this scales for you.
Two practical notes for existing repositories. First, the generic integration exists as an escape hatch if your agent is not among the supported ones, so tool choice does not block the pilot. Second, before refreshing project files with a forced init, protect anything customized outside the specs directory — the documentation specifically warns that shared project files, including the constitution and customized templates or scripts, can be overwritten.
Define Ownership for Living Specs
Ownership is where adoption succeeds or quietly stops. Three assignments, made once:
- Who approves a spec before implementation starts
- Who updates it when implementation reveals something the spec got wrong
- Who decides when a spec is obsolete
If the answer to the second is "whoever notices," the specs will be stale within a quarter. Attaching spec ownership to the same person who owns the code area is the least surprising arrangement, because it puts the update burden where the knowledge already is.
One structural note before you scale it: if the shape of your work is several agents running in parallel with plans reviewed before execution and results merged afterward, the constraint shifts from writing specs to coordinating review across parallel work. That is the category Verdent works in, and it is a different problem from choosing a spec format.
FAQ
How should teams version specs across long-running branches?
Version specs with the code that implements them, in the same branch and the same pull request. A spec on main that describes behavior only present in a feature branch is worse than no spec, because it is confidently wrong. For branches that live longer than a sprint, expect to reconcile the spec at merge time and budget review for it.
Can product managers approve specs without reviewing code?
Yes, and that is much of the point — a behavior-level spec is reviewable by people who do not read diffs. Two conditions make it work: the spec describes outcomes rather than implementation, and the approval is recorded on the spec itself rather than in a meeting. What product approval cannot cover is technical feasibility, so keep engineering sign-off on the plan as a separate gate.
What belongs in a spec versus an issue tracker?
The spec holds intended behavior and constraints — content that stays true after the work ships. The tracker holds status, assignment, priority, and dates — content that is meaningless once the work is done. When a ticket starts accumulating acceptance criteria that outlive the sprint, that content belongs in the spec, with the ticket linking to it.
How should security requirements be recorded in specs?
As behavioral constraints with explicit negatives, not as a checklist appended at the end. "Authenticated users can read only their own records" is verifiable; "follow security best practices" is not. Record what must not be possible alongside what must, since agents optimize for stated requirements and silently ignore unstated prohibitions.
When should a team archive an obsolete specification?
When the behavior it describes no longer exists in the product and no active work references it. Archive rather than delete: keep it readable in place, with a note pointing to whatever superseded it. If your persistence model treats completed feature directories as historical records, this happens naturally; if you edit specs in place, you need an explicit archive step or the obsolete text stays live indefinitely.
Related reading
- Once specs exist, the harder question is who owns an agentic workflow running across a team.
- For the review gate itself, see how automated review stays queue triage instead of an approval bot.
- When someone cites numbers for an agent workflow, what a benchmark like SWE-bench Pro can and cannot tell you is the right lens.
- For scoring a pilot consistently across tools, this harness evaluation checklist is reusable.
- If governance is the deciding constraint, this enterprise assistant review covers deployment and permission layers.
