Direct Answer

Spec Coding is a requirements-to-evidence discipline for AI-assisted software changes. A team defines scope, normative behavior, constraints, non-goals, risks, and acceptance evidence before implementation; humans or agents then produce code, and independent gates determine whether the implementation conforms.

The spec is not a long prompt, a generated checklist, or proof of quality. It is a versioned contract whose claims can fail.

Spec Coding Is Not New Requirements Engineering

The durable foundations predate generative AI. ISO/IEC/IEEE 29148 defines processes and information items for requirements engineering across system and software life cycles. RFC 2119 and RFC 8174 define requirement-level language such as MUST, SHOULD, and MAY for standards documents. Behavior-driven examples, design by contract, API-first development, model-based engineering, and acceptance-test practices all connect intent to verification.

AI changes the economics, not the need for engineering. When an agent can produce a large diff from a few sentences, missing assumptions propagate faster. Spec Coding adapts established requirements, traceability, and verification practices to an execution environment where implementation is cheap but review attention is scarce.

Claim Accurate boundary
“The spec replaces code” Code still defines deployed behavior; the spec defines intended behavior
“AI derives correct code from the spec” AI proposes an implementation; evidence determines conformance
“Specs eliminate ambiguity” Review exposes and reduces ambiguity; it cannot eliminate unknowns
“One document is the truth” Authority must be declared per decision and data type
“More detail is always better” Detail is useful only when it constrains a decision or verification

A Specification Is a Decision Contract

A useful specification allocates decisions before implementation begins.

Contract field Question it answers
Owner and status Who may approve or change this artifact?
Context and problem Which observed condition justifies the change?
Goals and outcomes Which user or system result must change?
Scope Which components, actors, and states are included?
Non-goals Which plausible adjacent changes are explicitly excluded?
Normative requirements What MUST, SHOULD, or MAY happen?
Scenarios Under which preconditions, events, and states?
Interfaces and data Which schemas, compatibility, and migration rules apply?
Quality attributes What limits apply to security, latency, reliability, privacy, and accessibility?
Evidence What independently proves each requirement?
Rollout and rollback How is exposure bounded and reversed?
flowchart LR A["Observed problem"] --> B["Reviewed specification"] B --> C["Design decisions"] C --> D["Implementation tasks"] D --> E["Code and configuration"] E --> F["Verification evidence"] F --> G{"Conforms?"} G -- No --> B G -- Yes --> H["Controlled release"]

The contract should distinguish fact, decision, assumption, and open question. An unverified assumption disguised as a requirement is one of the fastest ways to make an agent confidently implement the wrong system.

Write Requirements That Can Fail

A requirement is useful when a reviewer can determine whether it is satisfied.

text 
REQ-REFUND-001 (MUST)
Given an authenticated support operator
And an order owned by the operator's tenant
When the operator submits a refund draft
Then the service creates no financial transaction
And records the order ID, operator ID, policy version, and idempotency key.

Evidence:
- contract test: refund-draft-authority
- integration test: no-payment-side-effect
- audit assertion: required-fields-present

Avoid adjectives without measures: “fast,” “secure,” “user-friendly,” “robust,” and “scalable” are aspirations until the spec names a workload, threat, threshold, failure mode, or evaluation procedure. Use normative keywords sparingly; RFC 2119 explicitly warns that imperatives should be reserved for interoperability or harm-limiting requirements, not stylistic preference.

Separate Requirements, Design, Tasks, and Evidence

These artifacts answer different questions and should not silently overwrite one another.

Artifact Owns Must not pretend to own
Requirement Observable behavior and constraint File-level implementation
Design Architecture and selected trade-offs Business approval
Task Work decomposition and dependencies Proof of correctness
Test or review result Evidence for a requirement Requirement intent
Release manifest Exact deployed versions and rollback Product rationale

A completed task is only evidence that work was attempted. A passing generated test is evidence only after reviewers establish that its assertions correspond to the requirement. A deployed result is not conformant merely because the agent marked every checkbox.

Build Bidirectional Traceability

Traceability lets a team move from requirement to evidence and from changed code back to authorized intent.

flowchart LR R["Requirement ID"] --> S["Scenario"] R --> D["Design decision"] R --> T["Implementation task"] T --> C["Code change"] R --> E["Evidence"] C --> E E --> M["Release manifest"]

Maintain a small matrix for consequential changes:

Requirement Design Code / config Evidence Result
REQ-REFUND-001 ADR-014 refund-draft service contract + integration pass
REQ-REFUND-002 ADR-014 policy gateway authorization test pass
REQ-REFUND-003 ADR-021 audit emitter schema + retention review blocked

Forward traceability detects requirements with no implementation or evidence. Reverse traceability detects code and configuration changes with no authorized requirement. Both matter when agents modify adjacent files “helpfully.”

Control Change Instead of Freezing the Spec

A living specification changes through review, not through silent drift.

flowchart LR A["Draft"] --> B["Reviewed"] B --> C["Approved"] C --> D["Implementing"] D --> E["Verifying"] E -- "Deviation found" --> C E -- "Evidence passes" --> F["Released"] F -- "New approved revision" --> G["Superseded"]

When implementation reveals a missing case, stop and classify it:

  1. Defect in implementation: fix code; the spec remains authoritative.
  2. Defect in specification: revise the requirement, impact analysis, tasks, and evidence plan.
  3. New scope: create a separate change; do not smuggle it into the current diff.
  4. Emergency deviation: record approver, reason, expiry, compensating control, and reconciliation task.

Chat instructions must not override an approved artifact without leaving a versioned record.

Make the Spec Executable at the Right Layers

“Executable spec” does not mean every sentence generates code. It means important claims connect to enforceable or repeatable checks.

  • API behavior: OpenAPI or JSON Schema validation and contract tests.
  • Events: AsyncAPI/schema compatibility and consumer tests.
  • Authorization: policy tests at tenant, object, and action level.
  • Data changes: migration, rollback, invariants, and reconciliation.
  • User behavior: acceptance and accessibility tests.
  • Reliability: fault injection, timeout, retry, and recovery tests.
  • Performance: named workload, environment, percentile, and budget.
  • Security: threat cases, static/dynamic analysis, and manual review.

Some evidence remains human: product wording, legal interpretation, visual quality, or risk acceptance. Mark it as manual evidence with an owner instead of inventing automation.

Place Spec Coding Among Adjacent Practices

Spec Coding is a coordination layer, not a replacement for established engineering methods.

Practice Primary question Relationship
Vibe Coding Can we explore this idea quickly? Useful before intent stabilizes
Product discovery Is this problem worth solving? Supplies validated problem and outcome
Requirements engineering What must the system do and why? Core foundation
ADR / design review How and why will we implement it? Records trade-offs
TDD / BDD How do we express and verify behavior? Supplies executable evidence
API / schema first What interface contract must hold? Machine-checkable subset
Harness engineering How is agent execution constrained? Enforces process and runtime gates
CI/CD Can this revision be integrated and released? Runs conformance and release checks

OpenSpec and GitHub Spec Kit package different artifact workflows around these ideas. Their commands, templates, and supported integrations are versioned product behavior, not the definition of Spec Coding. Use the dedicated OpenSpec tutorial for tool operation and the AI coding spec guide for artifact-writing examples.

Right-Size the Method

Specification depth should scale with ambiguity, coordination, consequence, irreversibility, and lifetime.

Change Appropriate contract
Disposable prototype Goal, timebox, and delete condition
Small reversible bug fix Reproduction, expected behavior, regression test
Product feature Scope, non-goals, scenarios, data, evidence, rollout
Shared API Normative schema, compatibility, consumer evidence, deprecation
Data migration Invariants, reconciliation, capacity, rollback, ownership
Safety- or compliance-relevant change Formal review, full traceability, independent evidence, retained approvals

Do not use a large template for every change. Ceremony that no one reviews creates false confidence and consumes the same attention the method is meant to protect.

Common Failure Modes

  • Spec laundering: an agent writes the spec and immediately implements it without independent review.
  • Generated-test circularity: the same misunderstanding creates both code and assertions.
  • Document authority conflict: ticket, chat, spec, schema, and code disagree with no precedence rule.
  • Non-goal leakage: adjacent refactoring enters the diff without approval.
  • Checkbox conformance: task completion substitutes for behavioral evidence.
  • Stale contract: implementation changes but requirements and evidence links do not.
  • Tool theology: teams debate frameworks instead of requirement and evidence quality.
  • Compliance theater: traceability is claimed, but links cannot be followed during an audit.

Evaluate Whether Spec Coding Helps

Compare similar changes before and after adoption. Do not use generated lines or completed tasks as success metrics.

Measure:

  • clarification cycles before implementation;
  • review and rework minutes;
  • requirement coverage and orphan code changes;
  • escaped defects by requirement and risk slice;
  • lead time from approved intent to accepted change;
  • spec defects discovered during implementation;
  • rollback and incident rate;
  • total human and model cost per accepted change.

A useful trial preserves unsuccessful and abandoned changes. If documentation cost rises while accepted-change quality, review load, or recovery does not improve, simplify the process or stop using it for that change class.

Frequently Asked Questions

Is Spec Coding the same as SDD?

Usage is not standardized. This guide uses Spec Coding as the practical AI-assisted application of specification-driven development. Some sources use SDD for formal or model-driven methods; always define the artifact, authority, and verification level rather than relying on the label.

Must every requirement use Given/When/Then?

No. Scenario syntax works for behavior, but data invariants, security policies, performance budgets, interface schemas, and operational requirements need other forms. Choose the representation that makes the claim precise and verifiable.

Can an AI agent approve its own spec?

Not for consequential changes. An agent may draft, critique, and check consistency, but the accountable owner approves intent and risk. Independent tools or reviewers should evaluate the implementation.

Should the spec contain implementation details?

Only when they are true constraints. Mandate a protocol, schema, algorithm, dependency, or file boundary when compatibility, security, operations, or an approved architecture requires it; otherwise leave the design space open.

What is the smallest useful spec?

For a normal feature: owner, goal, context, scope, non-goals, normative scenarios, interfaces, quality constraints, evidence, rollout, and rollback. Remove fields that cannot affect a decision, but never omit how success and failure will be determined.

Primary Sources

  • ISO/IEC/IEEE 29148:2018 — requirements-engineering processes and information items; confirmed in 2024 and marked for revision.
  • RFC 2119 and RFC 8174 — normative requirement-level keywords and usage boundaries.
  • Microsoft: Spec-Driven Development — current industry framing, lifecycle alignment, and right-sized adoption.
  • GitHub Spec Kit — one current implementation of a specification-driven workflow.
  • OpenSpec — a separate artifact-guided implementation; product claims and commands are version-sensitive.