Spec-Driven Development: the control plane for AI-native software engineering

A coding agent can turn a short request into a surprising amount of code: APIs, schemas, migrations, tests, documentation, and a pull request. The useful question is no longer only can we implement this? It is increasingly do we agree on the intended behavior, constraints, and evidence of correctness?

This is the promise of Spec-Driven Development (SDD): not documentation for documentation’s sake, and not a return to frozen requirements. It is a way to make intent explicit, reviewable, versioned, and increasingly machine-actionable—so humans and coding agents can work against the same contract.

The shift: from code-centric to intent-centric delivery

Traditional engineering already had specifications: product requirements, design documents, API contracts, acceptance criteria, tests, and architecture decisions. The novelty is economic. When writing code was the expensive part, incomplete intent could sometimes be resolved through the slow, conversational work of implementation. When agents can produce a large implementation quickly, ambiguity scales into review load, duplicate abstractions, unsafe assumptions, and costly rework just as quickly.

The ideas are old. The economics are new.

SDD should not be presented as if software teams suddenly discovered requirements. It sits on a long line of practices: requirements engineering, design by contract, TDD, BDD, executable specifications, infrastructure as code, policy as code, and versioned architecture decisions. The new capability is that an agent can consume these artifacts directly and act on them. The new risk is that it can also act on a vague or wrong artifact at high speed.

The practical response is not to make every prompt longer. It is to make the decisions that shape a change explicit, reusable, and reviewable before agents multiply the implementation work.

Specifications as the intent layer

In an AI-native delivery system, the specification can become an explicit layer between human and business intent, technical planning, agent execution, code, and runtime evidence. It records what must be true, what must not change, who decides, and how the team will know the change worked. Code remains the executable implementation; the spec is the contract used to judge whether that implementation belongs.

SDD is context engineering—not context replacement

A serious coding task may depend on repository structure, Git history, API contracts, prior decisions, security policy, tests, operational practices, and product context. Dumping all of that into an agent context window is neither efficient nor reliable. A good specification is a curated compression of intent: it routes the relevant facts, constraints, scenarios, and evidence expectations to the task at hand.

But a specification cannot replace repository grounding. For brownfield work, an agent should inspect the actual codebase before proposing design. Otherwise it can invent a clean-sounding abstraction that duplicates an existing session service, cache repository, contract, or test harness.

Repository-grounded SDD: a practical workflow

The key addition is reconnaissance before design. A technical plan should cite the actual evidence it relies on. That makes an agent’s proposal reviewable and gives a future maintainer a path back to the surrounding system—not merely a generated explanation.

## Repository evidence

Existing implementation: src/auth/session.py
Existing abstraction: src/cache/redis_session_repository.py
Existing API contract: contracts/auth.yaml
Existing tests: tests/auth/test_session.py
Relevant decision: docs/adr/ADR-014-session-storage.md

Design constraint: extend the existing session path; do not create a parallel token service.

A layered artifact stack avoids one enormous spec

The answer is not a 100-page document for every change. Mature SDD separates durable principles from change-specific work, and separates behavior from implementation detail. Each layer has a different owner, lifetime, and review burden.

Make requirements testable: EARS plus scenarios

Kiro’s current Requirements-First workflow uses EARS-style requirements—typically WHEN condition, THE SYSTEM SHALL behavior—then derives design and tasks. That format is useful because it makes a hidden ambiguity visible. BDD complements it with observable GIVEN / WHEN / THEN examples. Neither notation guarantees that the underlying decision is right; both make it easier to challenge and verify.

AUTH-001 — idle session expiration

WHEN an authenticated session has been inactive for more than 30 minutes
THE SYSTEM SHALL reject the next authenticated request
AND require re-authentication.

Scenario: expired session
GIVEN an authenticated session with no activity for 30 minutes
WHEN the user makes another authenticated request
THEN the response is unauthorized
AND no protected resource is returned.

The requirement says what and why. The design decides how: where last activity is stored, how concurrent tabs behave, whether a long-running request extends activity, how a distributed store handles failure, what is logged, and which compatibility boundaries apply. Keeping these separate lets the behavior remain stable while implementation evolves.

From vague ticket to task contract

“Add automatic session timeout” is not an agent-ready task. It says nothing about the duration, activity definition, concurrent sessions, store failure, public APIs, migration behavior, security expectations, or proof of success. A bounded task contract puts the agent inside an explicit architecture envelope.

Task T-04 — implement idle-session expiration

Objective: satisfy AUTH-001 and AUTH-003.
Relevant components: src/auth/session.py, src/api/middleware.py
Do: extend the existing RedisSessionRepository; emit session_expired telemetry.
Do not: introduce a new token format or change public auth responses.
Verification: pytest tests/auth/test_session_timeout.py; contract test auth.yaml
Definition of done: requirements mapped, tests passing, telemetry documented.

Traceability is how intent survives high-speed change

A stable requirement ID is not bureaucracy when it lets a reviewer travel from a behavior to its design, task, implementation, test, pull request, and operational signal. This is especially valuable with agents: generated code can be abundant, but it should not be difficult to answer which requirement authorized it or which evidence supports it.

A matrix like this makes useful questions cheap: Which requirements have no test? Which changed after implementation started? Which code changed without a linked behavioral reason? The table is not proof by itself; it is a map for targeted review and automation.

Specification drift is the operating problem

SDD fails if the spec becomes a static artifact. Bug fixes, emergency changes, refactors, and operational learning can all make SPEC ≠ REALITY. Treat the loop as part of delivery: a behavior-changing pull request updates the relevant spec or records why it is intentionally unchanged; tests and runtime evidence expose gaps; the accepted current spec becomes the next task’s grounding.

• Use change proposals or delta specs for non-trivial changes.
• Make spec references and verification evidence visible in pull requests.
• Add contract and architecture checks where they are deterministic.
• Use independent agent analysis as a review aid, not as an unquestioned gate.
• Archive completed changes into the canonical behavior model so future work starts from current truth.

What today’s SDD tools teach us

GitHub Spec Kit, OpenSpec, and Kiro are useful examples of an emerging tool category—not interchangeable products and not evidence that one rigid workflow fits every team. Their important contribution is architectural: they make intent, plans, tasks, and change lifecycle artifacts first-class inputs to agent work.

Tool independence matters

Do not make one agent the sole holder of organizational intent. Markdown in Git, OpenAPI, JSON Schema, ADRs, test artifacts, and policy files are portable across Codex, Claude Code, Copilot, Kiro, and future tools. An agent should consume and improve the evidence; it should not trap the only version of the team’s reasoning in a proprietary chat history.

Human decision gates and independent verification

The right operating model is not “human writes every line” versus “agent does everything.” Humans provide the most leverage where ambiguity, irreversibility, values, and trade-offs are highest: approve intent, resolve genuine ambiguity, choose consequential architecture, define risk tolerance, and accept exceptions. Agents are excellent at structuring a draft, searching repository evidence, decomposing work, implementing bounded tasks, and assembling verification evidence.

For multi-agent work, the specification becomes even more important. A shared design contract and task graph can assign ownership boundaries—API contract, persistence, frontend, integration tests—while preventing four agents from making four incompatible assumptions. Parallelism without contracts simply moves merge conflicts and review debt downstream.

SDD does not replace Agile—it can prevent agentic Waterfall 2.0

Bad SDD writes a massive spec, freezes it, and implements for months while reality changes. Good SDD uses progressive rigor: discover enough intent to make the next safe decision, prototype or validate, update the living spec, and continue in small reviewable batches. The artifact set should grow with risk, not with a team’s appetite for paperwork.

Where Spec-Driven Development can go wrong

• Specification theater: documents exist but no planning, review, or CI decision actually uses them.
• AI-generated spec bloat: a model creates hundreds of requirements that no accountable human can inspect.
• False precision: a well-formatted requirement can encode a bad product assumption.
• Context blindness: the spec ignores repository evidence and the agent invents parallel abstractions.
• Architecture by agent: humans approve fluent generated designs without understanding consequences.
• Confirmation bias: the same agent drafts the spec, implementation, and verdict without independent challenge.
• Tool lock-in: intent survives only in one vendor’s chat or workspace.
• Metrics gaming: traceability coverage becomes the goal instead of useful behavior and operational quality.

Spec debt is intent uncertainty

Technical debt is accumulated implementation compromise. Spec debt is accumulated uncertainty about intent: undocumented behavior, contradictory requirements, stale decisions, tests with no known behavioral reason, or a capability with no clear owner. Agentic delivery can amplify both. A fast agent can add code to an already ambiguous system faster than a team can recover the reasoning behind it.

A realistic CI/CD future: deterministic checks first, probabilistic checks second

Some specification governance is practical today: enforce file structure, require a linked requirement ID for behavior-changing changes, validate schemas, run contract tests, lint policy, execute security checks, and verify coverage reports. Other checks—whether code “really” fulfills an ambiguous requirement, whether a design is coherent, or whether a spec is missing a subtle business rule—are judgment calls. An LLM can surface candidates, but it should report evidence and uncertainty rather than silently certify correctness.

From tests to runtime evidence

For critical non-functional requirements, tests are pre-production evidence—not the final proof. A requirement such as “API p95 latency SHALL remain below the agreed target” may need a benchmark, a rollout guardrail, and production telemetry. This connects SDD to SRE and governance: a specification is strongest when it has a measurable observation path after deployment.

A practical repository shape

project/
├── AGENTS.md
├── README.md
├── specs/
│   ├── constitution.md
│   ├── system/
│   │   ├── authentication.md
│   │   └── payments.md
│   └── changes/042-session-timeout/
│       ├── proposal.md
│       ├── requirements.md
│       ├── design.md
│       ├── tasks.md
│       ├── verification.md
│       └── decisions/
├── contracts/
│   ├── openapi.yaml
│   └── schemas/
├── src/
├── tests/
└── .github/

The exact folders do not matter as much as the lifecycle: durable principles are easy to find; current capability behavior is distinct from proposed change; implementation work is bounded; verification is preserved; and all of it moves through Git review with the code it governs.

Start small: an adoption sequence that will not stall delivery

• Choose one medium-risk, cross-cutting change where ambiguity or review cost is already visible.
• Create a short change spec with goal, non-goals, scenarios, constraints, and evidence requirements.
• Require repository evidence in the technical design; reject invented parallel abstractions.
• Break the work into small task contracts and preserve human approval for consequential decisions.
• Ask an independent reviewer—human, agent, or both—to report requirement coverage and missing evidence.
• Archive or update the spec after release, using operational evidence to correct what the team thought it knew.
• Only add heavier traceability or automation where the risk and coordination benefit justify it.

References and further reading