liveBook · Manning

Chapter 2: Writing Your First Specification

What you will learn in chapter 2 of Spec-Driven Development

The chapter introduces SDD as aligning human and agent intent through specifications and argues for understanding its foundations before choosing tools.

After this chapter you will be able to

What it builds on

Section by section

Introduction

The chapter introduces SDD as aligning human and agent intent through specifications and argues for understanding its foundations before choosing tools.

Key terms: intent alignment, specifications, durable artifacts, coauthoring, SDD tools, foundational concepts, specification

2.1 What is a specification

This section defines an SDD specification as a durable artifact that makes intent usable for implementation and explains why merely saving a prompt or plan is not enough.

Key terms: specification, artifact, intent, durable context, intent articulation, implementation constraints and boundaries, outcome verification, durability, prompt, plan

2.1.1 Tactical vs strategic context engineering

This section contrasts per-iteration prompts and plans with structured specifications that remain useful context for later implementation work.

Key terms: prompts, plans, tactical, context window, token budget, strategic context engineering, specifications, primary reference, information hierarchy, navigation guide

2.1.2 Characteristics of a good specification

This section explains four qualities of a good SDD specification: it captures decisions from dialogue, provides enough detail without excess, remains human-reviewable, and makes success verifiable.

Key terms: dialogue, intent, clarifying questions, accurate, not excessive, granularity, user story, acceptance criteria, human reviewable, primary control surface, model context

2.2 How does SDD work

This section explains how SDD turns articulated intent into specifications that guide an agent’s implementation and provide context for future work.

Key terms: intent harness, execution harness, SDD, specification, structured dialogue, operationalized intent, Intent as Target, durable context, existing body of specifications, computed intelligence

2.2.1 Spec-driven development workflow

This section explains how SDD turns an idea into a specification through separate Discover, Design, and Task conversations before a coding agent implements it.

Key terms: SDD, vibe coding, Discover, Design, Task, intent artifact, What, business context, purpose, scope

2.2.2 Why the structure matters

This section explains how durable artifacts and a separation between business intent and technical decisions make specifications usable across agent sessions and adaptable to architectural change.

Key terms: What, How, tasks, durable artifacts, compaction, business context, technical context, acceptance criteria, Technical Architecture, cache

2.3 Need for spec-driven development

This section explains why the upfront work of spec-driven development can be worthwhile despite the speed of one-line prompts.

Key terms: intent articulation, token usage, context-window management, course correction, durability of the specification as context, specification, return on investment

2.3.1 Vibe coding software development lifecycle

The URL-shortener exercise shows how vibe coding produces a working application quickly but lets unstated decisions, crowded conversation context, and lost reasoning make later changes less reliable.

Key terms: vibe coding, intent, alignment, course correction, dumb zone, context window, compaction, detail-oriented prompting spiral, new session, business policy

2.3.2 Context debt and the return to manual mode

The section explains how vibe coding accumulates context debt that can force a return to manual coding, and why plan mode helps with immediate misalignment without preserving durable shared understanding.

Key terms: context debt, durable context, intent articulation, mental model, vibe coding, context decay, context rot, cognitive debt, plan mode, build mode

2.3.3 Unsuitable for sustained independent execution by agents

This section explains why vibe coding limits an agent’s independent execution and makes that workflow expensive.

Key terms: vibe coding, course correction, conversational granularity, human steering, context windows, accumulated history, premium rates

2.3.4 Loss of predictability

Explains why vibe coding’s early speed can undermine delivery predictability and why sustainable agent-assisted development requires more than tactical context improvements.

Key terms: predictability of delivery, vibe coding, tactical context engineering, strategic context engineering, sustainable speed, agentic coding

2.4 Spec-driven development by example

Contrasts the URL shortener’s vibe-coding pass with SDD’s use of durable specifications to guide implementation.

Key terms: Execution Harness, Intent Harness, durable specifications, vibe coding

2.4.1 Are you ready to specify?

This section explains how to decide whether an idea is ready to specify and how disposable exploration can prepare it for specification.

Key terms: spec-ready, upstream of the spec, SDD tool, early version, what to leave out, specification, vibe coding, spike, exploration, first slice

2.4.2 SDD Framework Setup

This section sets up OpenSpec for the URL-shortener exercise and explains what the framework installs.

Key terms: SDD framework, OpenSpec, agent skills, commands, artifact structures, openspec init, spec-driven-url-shortener, openspec folder, skills, coding agent

2.4.3 Project Configuration

Configure the URL shortener’s project context so the coding agent receives it at the start of each session.

Key terms: openspec/config.yaml, project context, business domain, tech stack

2.4.4 Start specifying

This section shows how to create and review an OpenSpec proposal for the first slice of a URL shortener before asking an agent to implement it.

Key terms: Propose, Apply, Archive, Discover, Design, Task, change proposal, openspec-explore, openspec-propose, scope

2.4.5 Implement the specification

The section shows how to apply a completed change proposal, verify the implementation, and archive and synchronize its specifications as durable context for future work.

Key terms: change proposal, apply proposal skill, openspec-apply-change, tasks.md, durable context, README.md, specification files, Vibe coding, sync and archive, openspec/changes

2.4.6 Specify the next feature

The section shows how to specify and implement a second feature using durable specifications from the first feature, then update those specifications for the next change.

Key terms: durable artifacts, openspec/specs, Vibe coding, intent articulation, proposal.md, spec.md, design.md, tasks.md, Modified requirement, Deleted

2.5 What SDD Is Not

This introduction contrasts quick code generation with SDD’s structured approach to sustaining alignment and sets up a discussion of misconceptions.

Key terms: Vibe Coding, Spec-Driven Development, sustained alignment, structure

2.5.1 Dispelling the Waterfall Comparison

This section explains why SDD’s structured progression is not waterfall: teams can revisit decisions, specify one reviewable feature at a time, and revise specs after learning from implementation.

Key terms: SDD phases, phase-gating, waterfall, features, spec artifacts, humanly reviewable, shared understanding, intent artifacts, spec gap, regenerate the implementation

2.5.2 SDD adoption is not a developer tooling rollout

This section argues that SDD adoption depends on collaborative intent-building across roles, not merely installing developer tools or producing specification files.

Key terms: SDD adoption, SpecFall, developer tooling initiative, collaborative context-building, intent elicitation, conversation medium, context engine, solo SDD, product owner, architect

2.5.3 SDD more than recovers specification time through parallel execution

The section explains why SDD’s upfront specification time can pay off through more sustained, aligned agent execution and overlapping work.

Key terms: SDD, vibe coding, aligned implementation, approved specification, turn-by-turn supervision

2.5.4 SDD is not just a markdown machine

This section explains that SDD uses specifications to communicate intent, not merely to produce Markdown, and that specification structure should fit the work.

Key terms: Markdown artifacts, intent, specification, format, granularity, specification structures, workflow

2.6 Summary

The section recaps how durable specifications structure intent, prevent context debt, and support iterative, aligned agent execution.

Where this is used later

Concepts explained in this chapter

← Chapter 1: Introduction to Intent-Driven Development Chapter 3: Keeping Specs Alive →

These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.