2 Writing Your First Specification
Spec-driven development is introduced as a way to align human intent and AI execution before code is written, with specifications serving as durable artifacts that preserve decisions beyond a single chat session. The chapter argues that specs are not just documents, but structured, reviewable context that helps both people and agents understand what is being built, why it matters, and how success will be verified. It also distinguishes true specifications from disposable prompts or plans, emphasizing that durability alone is not enough unless the artifact is organized, precise, and grounded in dialogue.
The chapter contrasts tactical context engineering, which relies on prompts and short-lived plans, with strategic context engineering, which uses specifications as the primary reference for implementation and future maintenance. It explains that a good specification should support intent articulation, define constraints, and make outcomes verifiable, while remaining small enough for human review. The workflow is presented as a three-step conversation: discover the business need, design the technical approach, and break the work into tasks. This separation of what, how, and tasks helps preserve context, reduces token waste, and prevents business intent from getting tangled with technical decisions.
To show why this matters, the chapter walks through building a URL shortener first with vibe coding and then with SDD. The vibe coding example produces working software quickly, but it accumulates context debt, depends on repeated corrections, and becomes harder to evolve as the session grows stale or is compacted. In contrast, SDD uses OpenSpec to create proposal, design, spec, and task artifacts, then applies and archives them so future changes can build on durable context. The chapter closes by correcting common misconceptions: SDD is not waterfall, not a one-shot application spec, not just a developer tooling rollout, and not merely a markdown exercise; it is a collaborative way of building shared understanding that improves predictability, alignment, and long-term maintainability.
A mental model of SDD's role as part of the intent harness to elicit intent and operationalize it as specifications to engineer context for the execution harness.
The first interaction between human and agent is a discovery discussion, focused on business concerns to draft purpose, scope, etc. This then forms the basis of second interaction which focuses on design to decide technology stack, and architecture. Both of these together guide the drafting of the task list. The agent then uses the task list, to autonomously execute and generate the implementation.
Overview of the Discover phase in SDD.
Overview of the Design phase in SDD.
Overview of the Task phase in SDD.
Separation between the What and the How lets each evolve at its own pace. The same business context authored for a monolithic application can later drive a distributed implementation when the need arises.
Mental model of vibe coding, where a lack of clear intent articulation in the instruction/prompt leaves room for interpretation mistakes, and alignment at best depends on the vibe.
Plan mode makes the agent’s interpretation of our instruction explicit, reducing our dependence on the vibe.
Summary
- A specification in SDD is a structured, durable intent artifact, not a saved prompt, plan, or task list. It makes intent explicit, builds shared understanding, defines constraints, and makes outcomes verifiable.
- The What, How, and Tasks structure separates business intent, technical approach, and execution work. This keeps conversations focused, artifacts reviewable, and agent context clear.
- Vibe coding can move quickly, but it relies heavily on agent assumptions and current session context. As decisions accumulate without a durable structure, we build context debt, stay in a state of course correction, and lose speed, predictability, and control.
- SDD moves effort to the front of the process. By articulating intent before implementation, we reduce rework, support independent agent execution, and make parallel implementation more practical.
- SDD is not waterfall. It does not require specifying the entire application upfront or getting every specification right the first time. When implementation reveals a gap, the right move is to fix the spec and regenerate the implementation.
- SDD is not merely a tooling rollout or markdown generation workflow. Markdown may be the representation, but the real work is structuring human AI dialogue, capturing intent at the right level of detail, and creating durable context for aligned execution.
Spec-Driven Development ebook for free
