The Spec: Living Specifications for Agentic Development

Definition

A Spec is the durable, evolving source of truth for a feature. It defines how the system works (Design) and how we know it works (Quality).

Unlike traditional tech specs or PRDs that are “fire and forget,” specs are living documents in the sense defined by Cyrille Martraire: documentation that evolves alongside code rather than decaying in a separate system. They reside in the repository and change with every change to the feature—not as an afterthought, but as a first-class development artifact.

Birgitta Böckeler identifies three maturity levels for Spec-Driven Development:

1. Spec-first — A spec is written before implementation, then used for the task at hand and discarded.
2. Spec-anchored — The spec is kept alive after the task is complete, continuing to serve as context for evolution and maintenance of the feature.
3. Spec-as-source — The spec becomes the sole source file; humans never touch the generated code.

An Agentic SDLC operates at the spec-anchored level. Specs persist across a feature’s entire lifespan, accumulating lessons learned during implementation—what Kent Beck calls treating specs as “hypotheses, not verdicts.” Each implementation cycle refines the spec with discoveries from the field.

We explicitly reject the spec-as-source level as an anti-pattern. Deterministic code must remain the source of truth for runtime logic. Attempting to generate a codebase entirely from a spec sacrifices the agent control loop and regresses to the failures of Model-Driven Development—or as Böckeler warns, risks “the downsides of both MDD and LLMs: inflexibility and non-determinism.”

The Economy of Code

The cost of generating code has collapsed. Producing 10,000 lines of syntactically valid output is now effectively free. This inverts a decades-old assumption: the bottleneck in software development is no longer writing code, but articulating intent.

The Spec is the artifact that captures that intent. It defines what the system must do and why, so that generated code has Provenance—a traceable chain from requirement to implementation. Without a Spec, code generation produces volume without direction: output that cannot be verified, maintained, or trusted. In a word: “slop.”

The Problem: Context Amnesia

Agents do not have long-term memory. They cannot recall Jira tickets from six months ago or Slack conversations about architectural decisions. When an agent is tasked with modifying a feature, it needs immediate access to:

• The architectural decisions that shaped the feature
• The constraints that must not be violated
• The quality criteria that define success

Without specs, agents reverse-engineer intent from code comments and commit messages—a process prone to hallucination and architectural drift.

Traditional documentation fails because:

• Wikis decay — separate systems fall out of sync with code
• Tickets disappear — issue trackers capture deltas (changes), not state (current rules)
• Comments lie — code comments describe implementation, not architectural intent
• Memory fails — tribal knowledge evaporates when team members leave

Specs solve this by making documentation a first-class citizen in the codebase, subject to the same version control and review processes as the code itself.

State vs Delta

This is the core distinction that makes agentic development work at scale.

Dimension	The Spec	The PBI
Purpose	Define the State (how it works)	Define the Delta (what changes)
Lifespan	Durable (lives and evolves with the code)	Transient (closed after merge)
Scope	Feature-level rules	Task-level instructions
Audience	Architects, Agents (Reference)	Agents, Developers (Execution)

The Spec defines the current state of the system:

• “All notifications must deliver within 100ms”
• “API must handle 1000 req/sec”

The PBI defines the change:

• “Add SMS fallback to notification system”
• “Optimize database query for search endpoint”

The PBI references the Spec for context and updates the Spec when it changes contracts.

Why Separation Matters

Sprint 1: PBI-101 "Build notification system"
  → Creates /specs/notifications/spec.md
  → Spec defines: "Deliver within 100ms via WebSocket"

Sprint 3: PBI-203 "Add SMS fallback"
  → Updates spec.md with new transport rules
  → PBI-203 is closed, but the spec persists

Sprint 8: PBI-420 "Refactor notification queue"
  → Agent reads spec.md, sees all rules still apply
  → Refactoring preserves all documented contracts

Without this separation, the agent in Sprint 8 has no visibility into decisions made in Sprint 1.

The Assembly Model

Specs serve as the context source for Feature Assembly. Multiple PBIs reference the same spec, and the spec’s contracts are verified at quality gates.

flowchart LR
  A[/spec.md/]

  B[\pbi-101.md\]
  C[\pbi-203.md\]
  D[\pbi-420.md\]

  B1[[FEATURE ASSEMBLY]]
  C1[[FEATURE ASSEMBLY]]
  D1[[FEATURE ASSEMBLY]]

  E{GATE}

  F[[MIGRATION]]

  A --> B
  A --> C
  A --> D

  B --> B1
  C --> C1
  D --> D1

  B1 --> E
  C1 --> E
  D1 --> E

  A --> |Context|E

  E --> F

Anatomy

Every spec consists of two parts:

Blueprint (Design)

Defines implementation constraints that prevent agents from hallucinating invalid architectures.

• Context — Why does this feature exist?
• Architecture — API contracts, schemas, dependency directions
• Anti-Patterns — What agents must NOT do

Contract (Quality)

Defines verification rules that exist independently of any specific task.

• Definition of Done — Observable success criteria
• Regression Guardrails — Invariants that must never break
• Scenarios — Gherkin-style behavioral specifications

The Contract section implements Behavior-Driven Development principles: scenarios define what behavior is expected without dictating how to implement it. This allows agents to interpret intent dynamically while providing clear verification criteria.

For detailed structure, examples, and templates, see the Living Specs Practice Guide.

Relationship to Other Patterns

The PBI — PBIs are the transient execution units (Delta) that reference specs for context. When a PBI changes contracts, it updates the spec in the same commit.

Feature Assembly — Specs define the acceptance criteria verified during assembly. The diagram above shows this flow.

Experience Modeling — Experience models capture user journeys; specs capture the technical contracts that implement those journeys.

Context Engineering — Specs are structured context assets optimized for agent consumption, with predictable sections (Blueprint, Contract) for efficient extraction.

Behavior-Driven Development — BDD provides the methodology for the Contract section. Gherkin scenarios serve as “specifications of behavior” that guide agent reasoning and define acceptance criteria.

Specs as Living Hypotheses

A spec is not a waterfall requirements document sealed before implementation begins. It is a hypothesis—a structured bet on how a feature should work, designed to be refined as the team learns.

This aligns with the double diamond model of design: the second diamond (Develop → Deliver) is where implementation reveals unknowns. Edge cases surface, performance assumptions break, and new requirements emerge from contact with reality. A spec-anchored approach expects this. The spec is the artifact that captures what the team learns, making discoveries durable across agent sessions and team rotations.

Kent Beck frames this precisely: “A specification should function as a hypothesis, not a verdict.” And crucially: “Implementation doesn’t invalidate a spec. Implementation completes it.” The failure mode is not having specs—it is failing to update them when implementation teaches you something new.

The refinement cycle:

1. Initial Spec — Capture known constraints (API contracts, quality targets, anti-patterns)
2. Implementation Discovery — Agent or human encounters edge cases, performance issues, or missing requirements
3. Spec Update — New constraints committed alongside the code that revealed them
4. Verification — Gate validates implementation against updated spec
5. Repeat

This is the Learning Loop applied to specs: the spec doesn’t prevent learning—it captures learnings so agents can act on them in future sessions. The spec grows smarter with every implementation cycle, becoming what Böckeler describes as a “living, executable artifact that evolves with the project.”

Relationship to Other Patterns

The PBI — PBIs are the transient execution units (Delta) that reference specs for context. When a PBI changes contracts, it updates the spec in the same commit.

Feature Assembly — Specs define the acceptance criteria verified during assembly. The diagram above shows this flow.

Experience Modeling — Experience models capture user journeys; specs capture the technical contracts that implement those journeys.

Context Engineering — Specs are structured context assets optimized for agent consumption, with predictable sections (Blueprint, Contract) for efficient extraction.

Behavior-Driven Development — BDD provides the methodology for the Contract section. Gherkin scenarios serve as “specifications of behavior” that guide agent reasoning and define acceptance criteria.

Product Requirement Prompt — Convergent framework that independently arrived at the same structure: Goal + Why + Success Criteria maps to Blueprint + Contract. See the PRP page for the full structural comparison.

Living Specs Practice Guide — Implementation instructions, templates, and maintenance practices for this pattern.

Triple Debt Model — Specs are the primary mitigation for Intent Debt. Without externalized intent, every future modification — by human or agent — is a blind guess.