Spec-Driven Development with Coding Agents

Coding agents can produce code faster than a team can review it. That makes the quality of the instructions and checkpoints around the code more important, not less important.

Spec-driven development (SDD) gives the agent a chain of reviewable artifacts instead of one large prompt:

1. requirements define the behavior and constraints
2. design explains the technical approach and tradeoffs
3. tasks divide the design into executable changes
4. verification connects the implementation back to the requirements

The goal is not to predict every detail before coding. The goal is to make intent, decisions, and evidence visible enough that humans and agents can detect when the work is moving in the wrong direction.

A Spec Is More Than A Plan

A prompt, plan, and specification answer different questions.

Artifact	Main question	Typical lifetime	Common failure
Prompt	What should the agent do now?	One interaction	Important context remains implicit
Plan	How will this change be implemented?	One task or pull request	The plan optimizes a poorly defined outcome
Specification	What behavior must exist, why, and under which constraints?	A feature, change, or product capability	It becomes stale or too large to review
Verification evidence	What proves the required behavior exists?	Test and release history	Passing checks do not cover the actual requirement

A useful specification is not merely a longer prompt. It is a contract that can be questioned before implementation and checked after implementation.

This also distinguishes SDD from casual “vibe coding.” In an unstructured session, the human repeatedly steers the agent by reacting to generated code. In SDD, much of that steering is made explicit before and during implementation through artifacts that can be reviewed, versioned, and tested.

The Core Feedback Loop

SDD is sometimes presented as a straight sequence, but real development is iterative. Design can expose missing requirements. Implementation can expose an invalid design assumption. Testing can reveal that an acceptance criterion was incomplete.

flowchart TD
    A["Intent and problem"] --> B["Discover unknowns"]
    B --> C["Requirements<br/>behavior and constraints"]
    C --> D["Design<br/>approach and tradeoffs"]
    D --> E["Tasks<br/>executable changes"]
    E --> F["Implementation"]
    F --> G["Verification evidence"]
    G --> H{"Meets the specification?"}
    H -->|Yes| I["Review and release"]
    H -->|No| B
    D -->|Feasibility changes scope| C
    F -->|Implementation discovery| D

The feedback arrows matter. Without them, a generated specification can become a rigid waterfall document that protects an early mistake.

The Four Working Artifacts

File names vary by tool. requirements.md, design.md, and tasks.md are common, but the names are less important than the separation of concerns.

1. Requirements: What Must Be True

Requirements describe observable behavior and constraints without prematurely deciding every implementation detail.

They should capture:

• the user or system outcome
• acceptance criteria
• functional behavior
• non-functional constraints such as latency, availability, privacy, and accessibility
• error and boundary cases
• compatibility requirements
• explicit non-goals
• unresolved questions

Requirements should not silently embed a preferred implementation.

Weak:

Store sessions in Redis.

Better:

Authenticated sessions must survive an application restart.
Session lookup must remain below the agreed latency target at expected load.
The design must work with the infrastructure already approved for this service.

The second version leaves room to compare Redis with an existing database, a managed session service, or another suitable design. If Redis is mandatory, state why as a constraint rather than disguising it as the outcome.

2. Design: How The Requirements Will Be Met

The design translates behavior into a technical approach. It should be grounded in the current codebase, not generated from generic architecture patterns.

A useful design covers:

• relevant existing components and ownership boundaries
• proposed components, interfaces, and data flow
• alternatives considered and why they were rejected
• data model and migration impact
• authentication, authorization, privacy, and abuse cases
• failure handling, retries, and idempotency
• observability and operational support
• rollout and rollback strategy
• testing strategy
• requirement IDs addressed by each design decision

For an existing repository, require file paths, symbols, commands, or documentation links that support the design. An agent should not claim that a reusable abstraction exists without pointing to it.

3. Tasks: How The Design Will Be Executed

Tasks should be small enough to verify and large enough to deliver a meaningful increment.

Each task should identify:

• the requirement and design decisions it implements
• expected files or system boundaries
• dependencies on earlier tasks
• the observable completion condition
• the check that must pass
• whether the task is required or optional

Weak:

Implement password reset.

Better:

TASK-3 implements REQ-2 and DES-4.

Add one-time reset-token persistence behind the existing account repository.
Do not change the public login response schema.

Complete when:
- token values are stored only as hashes
- expired and consumed tokens are rejected
- focused repository and service tests pass

Prefer vertical slices over layer-only batches when possible. “Add the database schema, service behavior, API response, and focused tests for one requirement” is easier to review than generating every database change, then every service, then every endpoint across a large feature.

4. Evidence: How Completion Is Demonstrated

Completion is not the agent saying “done.” It is evidence connected to the specification.

Evidence can include:

• unit and integration test output
• contract or schema validation
• screenshots and accessibility checks
• load-test results
• migration dry runs
• security scans
• logs or traces from a controlled environment
• manual approval for behavior that cannot be automated safely

The evidence artifact does not need to be a separate file. It can be a traceability table in the pull request, test names containing requirement IDs, or links from tasks to CI results.

Choose The Right Starting Point

Not every change should begin with product requirements.

Starting point	Best when	First artifact
Requirements-first	Desired user behavior is known but architecture is flexible	Requirements and acceptance criteria
Design-first	Architecture, migration, or technical constraints drive the change	Technical note or design
Bug-first	Existing behavior is wrong and regression risk matters	Reproduction, root cause, preserved behavior, fix criteria
Research-first	Important facts or technology choices are unresolved	Findings, sources, experiments, and recommendation
Quick plan	The change is understood and low risk	Short scope, tasks, and verification list

Current Kiro Feature Specs support both requirements-first and design-first workflows, while Kiro’s web workflow also distinguishes feature, bug, and quick-plan work. GitHub Spec Kit provides a tool-neutral Spec to Plan to Tasks to Implement process for multiple coding agents.

These are implementations of the idea, not the definition of it. A team can use the same method with ordinary Markdown and any capable coding agent.

Scale The Ceremony To The Risk

A full specification has a cost. Use it where reviewable intent reduces more risk than the process adds.

Change	Appropriate artifact set
Typo or mechanical rename	Prompt plus build or lint check
Small, well-understood fix	Reproduction, scoped plan, regression test
Multi-file feature	Requirements, design notes, tasks, verification map
Migration, security, billing, or permissions	Full spec with review gates, rollout, rollback, and audit evidence
Exploratory prototype	Hypothesis, time box, learning criteria, throwaway boundary

Use a full spec when:

• several people must agree on behavior
• requirements interact or conflict
• the change crosses components or repositories
• failure is expensive or difficult to reverse
• an agent will work autonomously for a long period
• the resulting decisions must survive the chat session

Do not use a full spec to make a one-line change look important.

Writing Requirements Agents Can Execute

Give Requirements Stable IDs

IDs make traceability possible.

### REQ-1: Generic reset response

When a visitor submits a password-reset request, the account API shall return
the same public acknowledgement whether or not the email belongs to an account.

Rationale: prevent account enumeration.

Without a stable ID, phrases such as “the reset requirement” become ambiguous as the document changes.

Write Observable Acceptance Criteria

An acceptance criterion should describe something a test or reviewer can observe.

Vague	Observable
The page should load quickly	At the agreed test load, the page’s p95 server response time is below 300 ms
Errors should be handled gracefully	A failed dependency returns the documented error state without losing the user’s draft
Use secure tokens	Reset tokens contain at least the approved entropy, expire after 15 minutes, are single-use, and are stored only as hashes
The UI should be accessible	The flow passes the selected automated checks and its keyboard path is manually verified

Do not invent numeric targets just to make a sentence measurable. Targets must come from product, security, compliance, or operational owners.

Separate Functional And Non-Functional Requirements

Functional requirements describe behavior:

When a valid reset token is submitted with an acceptable password,
the account service shall replace the password and invalidate the token.

Non-functional requirements constrain how the behavior is delivered:

The service shall not write raw reset tokens or new passwords to application logs.

Security, latency, availability, data retention, localization, accessibility, and compatibility are often omitted because they are not visible in the happy path. Give them their own review pass.

Use EARS Where Structured Language Helps

EARS stands for Easy Approach to Requirements Syntax. It uses a small set of keywords to constrain natural-language requirements without requiring a formal specification language.

Pattern	Use	Example
Always active	A rule that is continuously true	The account service shall never store a raw reset token
State-driven	Behavior while a state is true	While an account is locked, the service shall reject password login
Event-driven	Response to a trigger	When five failed logins occur within ten minutes, the service shall lock the account
Optional feature	Behavior only when a feature exists	Where enterprise SSO is enabled, the login page shall show configured identity providers
Unwanted behavior	Response to an error or undesirable event	If a reset token is expired, then the service shall reject it without changing the password
Combined	State plus event or error conditions	While maintenance mode is active, when a login is attempted, the service shall return the maintenance response

EARS can improve consistency and testability, but syntax alone does not make a requirement correct. A perfectly structured sentence can still encode the wrong user need, omit an important boundary, or use an undefined term.

Review Requirements Before Design

Ask the following questions:

• Who or what receives the value?
• Is the behavior observable?
• Are terms such as “fast,” “large,” “recent,” or “secure” defined?
• Are time, ordering, concurrency, and retry behavior explicit where relevant?
• What happens at minimum, maximum, empty, expired, duplicate, and interrupted states?
• Do any requirements conflict?
• Are external systems and policy assumptions supported by current sources?
• Which decisions still require a human owner?
• What must not change?

For a complex requirement set, ask an agent to perform a separate consistency review rather than immediately generating a design. Current Kiro tooling includes an Analyze Requirements pass for inconsistencies, ambiguities, conflicting constraints, missing definitions, and edge cases. The same review can be requested from any agent, but its findings still need human judgment.

Review these requirements without proposing implementation yet.

Find:
- ambiguous or undefined terms
- conflicting requirements
- missing failure, boundary, and concurrency cases
- solution choices disguised as requirements
- non-functional constraints that need an owner or measurable target

For every finding, cite the affected requirement IDs and propose a clarification.
Do not silently rewrite product intent.

Build Traceability Through The Workflow

Traceability answers a simple question: can we follow each important requirement through design, implementation, and evidence?

flowchart LR
    R1["REQ-1<br/>generic public response"] --> D1["DES-2<br/>uniform API result"]
    D1 --> T1["TASK-2<br/>handler and mail boundary"]
    T1 --> V1["TEST-5<br/>known and unknown email"]
    V1 --> E1["CI evidence"]

    R2["REQ-2<br/>single-use token"] --> D2["DES-4<br/>hashed token record"]
    D2 --> T2["TASK-3<br/>token lifecycle"]
    T2 --> V2["TEST-8<br/>state transition cases"]
    V2 --> E1

A lightweight matrix is often enough:

Requirement	Design	Tasks	Verification	Status
REQ-1	DES-2	TASK-2	API integration test	Covered
REQ-2	DES-4	TASK-3	Token lifecycle tests	Covered
NFR-1	DES-5	TASK-4	Log-capture assertion	Covered
NFR-2	Not decided	None	None	Blocked

The uncovered row is valuable. It prevents a polished task list from hiding a missing design decision.

Traceability should remain cheap enough to maintain. Do not build a large requirements database for a small application unless regulation, safety, or organizational scale justifies it.

Tie Verification To Requirements

Acceptance criteria and tests are related, but they are not identical.

• an acceptance criterion states required behavior
• a test checks selected examples or properties of that behavior
• evidence records what actually ran and what happened

One requirement may need several test levels. A password-reset rule might need a pure token-expiry unit test, repository integration tests, an API response test, and a browser-level user-flow check.

Where Property-Based Testing Fits

Example-based tests check cases selected by a developer:

expired token -> rejected
used token -> rejected
valid token -> accepted

Property-based testing defines a behavior that should remain true across many generated inputs or operation sequences:

For every token lifecycle, no token can successfully reset a password more than once.

Good candidates include:

• encode then decode returns the original value
• serialization and deserialization preserve meaning
• retries do not duplicate an idempotent operation
• balances are conserved across valid transfers
• access never increases after a permission is removed
• a state machine never enters a forbidden state

Property-based tests are powerful, but they are not automatic proof that the implementation satisfies the full specification. Confidence depends on:

• whether the property expresses the real requirement
• whether the input strategy covers the meaningful domain
• whether the test oracle is correct
• whether integrations and environmental failures are also tested

The Hypothesis documentation explicitly presents property-based testing as a useful addition to ordinary unit testing, not always a replacement.

Also watch for shared-assumption failure: if the same agent writes the requirement, design, implementation, and test, all four can encode the same misunderstanding. Human review, independent examples, production evidence, and separate adversarial review passes reduce that risk.

Use Tools During Specification, Not Only Coding

An agent should not design from its pretrained memory when current evidence is available.

Useful sources include:

• the current repository and history
• issue trackers and product decisions
• API schemas and generated clients
• architecture records
• current vendor documentation
• logs, traces, and incident reports
• database schemas and sample data
• design mocks and accessibility requirements
• MCP servers that expose approved internal systems

Use tools in every phase:

Phase	Useful tool activity
Requirements	Read tickets, interview notes, policies, analytics, and current behavior
Design	Inspect code paths, dependencies, schemas, APIs, and current documentation
Tasks	Confirm file ownership, build commands, test boundaries, and dependency order
Implementation	Edit, execute, inspect failures, and record deviations
Verification	Run checks, capture evidence, compare against requirement IDs

Tool access improves grounding, but it also creates security and freshness concerns. Restrict permissions, identify authoritative sources, record when evidence was retrieved, and do not treat an arbitrary search result as a product requirement.

Challenge The Initial Solution

Prompts anchor agents. If the first sentence says “store sessions in S3,” the resulting requirements and design may rationalize S3 instead of evaluating the actual persistence need.

Before approving the design, ask:

Identify solution choices embedded in my request.

Restate the underlying outcomes and constraints without those choices.
Research the current codebase and authoritative documentation.
Compare at least two viable approaches, including the proposed one.
Explain the operational, security, migration, and maintenance tradeoffs.

This does not mean the agent must challenge every decision. It means important decisions should be intentional rather than accidental prompt wording.

Applying SDD To Existing Codebases

Greenfield examples are easy because the agent can invent a coherent architecture. Brownfield work is where discipline matters most.

Start with the delta, not a specification for the entire existing system.

1. Map the current code path and ownership boundaries.
2. Record current observable behavior, including behavior that must remain unchanged.
3. Reproduce the problem or establish characterization tests.
4. Define the required change and non-goals.
5. Identify architecture and migration constraints from repository evidence.
6. Design the smallest safe transition.
7. Break implementation into reversible, verifiable slices.

Agent performance in a large repository depends on the same qualities that help humans:

• clear module boundaries
• cohesive responsibilities
• reliable tests
• discoverable build and run commands
• current local documentation
• manageable dependency graphs

A specification does not repair a tangled codebase. It can, however, make the risk visible and stop the agent from pretending a broad rewrite is a routine feature task.

For unfamiliar repositories, use Codebase Onboarding with Coding Agents and Finding Unknowns Before Agentic Work before finalizing the spec.

Decide What Happens After Merge

Specs become harmful when nobody knows whether they are temporary plans, historical records, or current contracts.

GitHub Spec Kit’s persistence guidance distinguishes several useful choices.

How Long The Spec Matters

Model	Meaning	Main risk
Spec-first	Use the spec to guide implementation, then allow it to become historical or be removed	Future work cannot rely on it as current truth
Spec-anchored	Keep the spec and use it as context for later changes	It can drift unless ownership is clear
Spec-as-source	Treat the spec as the primary human-edited contract and derive other artifacts from it	Regeneration can lose implementation rationale

How Changes Flow

Model	Change rule	Good fit	Watch for
Flow-back	Any artifact can change, then the set is reconciled	Fast, collaborative iteration	Silent divergence between requirements, design, tasks, and code
Flow-forward	Create a new change spec instead of mutating the completed one	Audit trails and historical clarity	Fragmented decisions across many specs
Living spec	Update the requirement contract, then revise or regenerate derived artifacts	Stable product contracts	Old rationale disappearing during regeneration

Choose one convention explicitly. Add status and ownership to the artifact:

status: active
owner: identity-platform
last_validated: 2026-07-18
implementation:
  - src/account/reset-service.ts
verification:
  - tests/account/reset-flow.test.ts

The date does not prove correctness. It tells a future reader when somebody last checked the relationship.

Worked Example: Password Reset

Intent

Allow account owners to reset a forgotten password without exposing whether an
email address has an account and without allowing a reset token to be reused.

Requirements

## REQ-1: Public acknowledgement

When a visitor submits a syntactically valid email address to the reset endpoint,
the account API shall return the same public acknowledgement regardless of
whether the email belongs to an account.

## REQ-2: Reset-token lifecycle

Where the email belongs to an active local account, the account service shall
create a cryptographically suitable, single-use reset token that expires after
the security team's approved duration.

If a reset token is expired, consumed, or invalid, then the account service
shall reject the password change without modifying the account.

## NFR-1: Secret handling

The system shall not persist or log raw reset tokens or submitted passwords.

## Non-goals

- changing enterprise SSO recovery
- changing login-session duration
- redesigning the email-delivery service

The duration is deliberately not invented. It remains an explicit decision for the security owner.

Design Decisions

## DES-1: Preserve the public API shape

Known and unknown emails return the existing generic response. Mail dispatch
occurs behind the service boundary and does not alter the public result.

Addresses: REQ-1.

## DES-2: Store only a token hash

Generate the raw token once, send it through the existing mail abstraction,
and persist only its hash, account ID, expiry, and consumed timestamp.

Addresses: REQ-2 and NFR-1.

## DES-3: Consume atomically

Validate and mark the token consumed in one transaction so concurrent requests
cannot both succeed.

Addresses: REQ-2.

Tasks And Evidence

Task	Requirements	Completion evidence
Add hashed token record and repository operations	REQ-2, NFR-1	Repository tests cover expiry and atomic consumption
Implement uniform reset-request response	REQ-1	API test compares known and unknown email responses
Implement password replacement transaction	REQ-2	Integration tests cover valid, expired, invalid, used, and concurrent requests
Add secret-handling assertions	NFR-1	Captured logs contain neither raw tokens nor passwords

This is enough structure to make the work reviewable without specifying every class name before the agent inspects the repository.

A Reusable Specification Template

# <Change Name>

status: draft
owner: <team or person>
reviewers: <product, engineering, security, operations as needed>

## Problem And Outcome

What problem exists? Who experiences it? What observable outcome should change?

## Current Evidence

- repository paths:
- logs or incidents:
- product or policy sources:
- assumptions not yet verified:

## Requirements

### REQ-1: <short name>

<Observable behavior and rationale>

Acceptance criteria:
- <criterion>
- <criterion>

### NFR-1: <quality or operational constraint>

<Measurable target or named owner who must define it>

## Edge And Failure Cases

- empty and boundary values
- retries, duplicates, and concurrent actions
- dependency failure and timeout
- authorization and privacy failure
- migration and rollback behavior

## Non-Goals

- <explicitly excluded work>

## Open Questions

- <decision, owner, and blocking status>

## Design

### Existing System

<Relevant files, components, interfaces, and constraints>

### Proposed Approach

<Components, data flow, interfaces, security, operations, rollout, rollback>

### Alternatives Considered

| Option | Advantages | Costs and risks | Decision |
|---|---|---|---|

### Requirement Mapping

| Requirement | Design decision | Verification approach |
|---|---|---|

## Tasks

- [ ] TASK-1: <change, requirement IDs, dependencies, and completion check>
- [ ] TASK-2: <change, requirement IDs, dependencies, and completion check>

## Verification Evidence

| Requirement | Check | Result or link |
|---|---|---|

## Deviations

<Implementation discoveries and the artifacts updated because of them>

Prompts For Each Review Gate

Requirements Gate

Inspect the current repository and the supplied product evidence.
Draft requirements only. Do not design or implement yet.

Include stable IDs, acceptance criteria, non-functional constraints,
edge cases, non-goals, and open questions. Cite repository paths or current
sources for claims about existing behavior. Do not invent numeric targets.

Design Gate

Design an implementation for the approved requirements.

Map every design decision to requirement IDs. Ground the proposal in files and
interfaces you inspected. Compare meaningful alternatives. Cover data,
security, failure handling, observability, migration, rollout, rollback, and
verification. Stop if a requirement is infeasible or contradictory.

Task Gate

Break the approved design into dependency-aware, verifiable tasks.

Each task must reference requirement and design IDs, state its expected scope,
and name the check that proves completion. Prefer small vertical slices. Do not
include unrelated cleanup.

Implementation Gate

Implement only the approved tasks.

After each meaningful task, run its focused check and record evidence. If the
codebase contradicts the spec, stop and update the affected requirement,
design, or task through review instead of silently improvising.

Completion Gate

Audit the implementation against every requirement ID.

Show the requirement-to-design-to-task-to-test mapping, command output, and any
manual evidence. List uncovered requirements, deviations, stale artifacts, and
remaining risk. Do not mark complete while a required row is uncovered.

Common Failure Modes

Failure	Why it happens	Better approach
Giant generated documents	The agent equates detail with quality	Limit each artifact to decisions that affect implementation or verification
Requirements describe technology	The initial prompt anchors on a solution	Restate outcomes and compare alternatives before design
One-way workflow	Teams treat approved text as immutable	Feed design, implementation, and test discoveries back through review
Tasks lose requirement context	The task list becomes the only artifact the agent sees	Carry IDs and acceptance criteria into each task
Tests mirror the same misunderstanding	One agent authors every artifact from one assumption	Add independent examples, adversarial review, and human validation
Specs drift after merge	No persistence model or owner exists	Declare whether the spec is temporary, historical, anchored, or authoritative
Full ceremony for trivial work	Process is applied mechanically	Scale the artifact set to complexity and risk
Tools provide untrusted context	The agent treats every retrieved source as authoritative	Restrict access and identify approved sources explicitly

What Spec-Driven Development Does Not Solve

SDD does not automatically provide:

• correct product strategy
• complete requirements
• trustworthy source data
• sound architecture
• secure permissions
• reliable tests
• human accountability

It makes these concerns easier to inspect. It cannot replace the people responsible for them.

Key Takeaways

• A specification defines behavior, constraints, and evidence; a plan mainly defines implementation steps.
• Requirements, design, tasks, code, and tests should form a traceable chain.
• The workflow must allow discoveries to flow backward, or it becomes rigid waterfall.
• Structured language such as EARS helps testability but does not guarantee correct intent.
• Property-based testing is useful for invariants, not automatic proof of the whole specification.
• Tool use belongs in requirements and design as well as implementation.
• Brownfield success still depends on repository structure, tests, and current evidence.
• Decide whether specs are temporary, historical, anchored, or authoritative before they drift.
• Use the smallest amount of ceremony that matches the cost of being wrong.

Resources

• Spec-Driven Development: Agentic Coding at FAANG Scale and Quality - source talk by Al Harris
• Kiro Feature Specs
• Kiro Web Specs
• Kiro requirements analysis
• GitHub Spec Kit documentation
• GitHub Spec Kit repository
• Spec persistence models
• EARS official guide
• Original EARS publication record
• Hypothesis property-based testing introduction
• Plan Before You Code
• Verification-Driven Agentic Coding