liveBook · Manning

Specification

As explained in Spec-Driven Development

A structured description of software intent, requirements, implementation constraints, and expected outcomes.

A specification is a structured, durable artifact that turns software intent into a target humans can review and coding agents can implement. It records what should happen, the constraints that shape the solution, and how to verify the outcome. A saved prompt or task list alone is not a specification: it may direct one session without preserving the decisions needed for later changes. section 2.1 section 2.6

The central problem is not whether an agent can generate code from a brief request; it is how much the agent must guess. Author the specification through dialogue: state the purpose, let the agent probe ambiguities, review its proposed decisions, and retain only the detail needed to prevent consequential assumptions. The result should be a primary reference for behavior, organized so relevant context can be retrieved without reconstructing intent from chat history or code. section 2.1.2 section 2.1.1

Separate the conversations before implementation, then revisit them as the feature evolves:

  • Discover what the feature is for, who needs it, its scope, and its observable outcomes. section 2.2.1
  • Design the technical approach and constraints; derive tasks for execution rather than mixing every decision into one prompt. section 2.2.1 section 2.6
  • Use the reviewed artifacts to guide implementation and validation. Specify features incrementally; revise earlier decisions when implementation exposes a gap. section 2.2 section 2.5.1

A URL shortener’s first slice

A bounded proposal asks the agent to clarify scope before drafting: anonymous users submit a long URL, receive a short URL, and follow it to the original. The artifacts distinguish purpose and exclusions, design choices, requirements with valid- and invalid-URL scenarios, and implementation tasks. Initially, links remain permanent and features such as accounts, custom aliases, and click tracking stay out of scope. A later request for 90-day expiry modifies existing behavior; reviewing the prior specification exposes decisions that a code-only change might miss. section 2.4.4 section 2.4.6

Keep the specification authoritative after code generation. If testing reveals that malformed URLs cause a server error, a direct code patch fixes the symptom but leaves future agents with the same vague instruction to “validate input.” Clarify the rejection rule and expected response in the specification, then bring implementation back into line. If the rule was discussed but lost when written down, improve the artifact’s format; if it was never discussed, improve the questions asked. section 3.1.1 section 3.2.2 section 3.1

Listing 3.2 Capturing malformed URL validation in Gherkin format
Feature: Shorten URL
  Scenario: Reject malformed URL
    Given the user submits a malformed URL
    When the shorten URL request is processed
    Then the service returns the expected validation status
    And the response explains the validation failure
    And no short link is stored

The validation scenario makes the expected response and absence of a stored link explicit, rather than leaving “return an error” open to interpretation. section 3.2.2

How Spec-Driven Development covers it

How deep it goes
Defines essential properties and works through authoring, revision, and intent-loss repairs; leaves format and granularity dependent on the change.
Examples
Uses URL-shortener proposals, requirements, tasks, an expiry change, and malformed-URL validation to expose specification gaps.
What it assumes
Assumes familiarity with software features and coding agents; treats uncertain product intent as something to explore before specifying.
What you can do after
Practice/perform specification-first changes: clarify intent, review artifacts, and repair discovered gaps before relying on generated implementation.
How it connects
Connects intent articulation, context engineering, acceptance criteria, spec-driven development, and implementation validation.

Also explained in

Compare how 12 books explain specification →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Spec-Driven Development. The section links point to the parts of the book it draws on.