Chapter 2: Writing Your First Specification
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
- Specifications as shared intent. Explain how specifications support intent alignment between humans and agents before implementation and preserve that understanding beyond one interaction. Describe how coauthoring a specification with AI can clarify human intent.
- Specification as durable context. Explain how an SDD specification makes intent explicit and provides shared, reusable context for humans and AI to produce aligned implementations. Describe what the section means by an artifact.
- Three specification responsibilities. Describe how specification authoring elicits intent through human–AI dialogue, sets implementation constraints and boundaries, and states how to verify that the outcome is aligned.
- Durability is not sufficient. Distinguish a complete SDD specification from a prompt, plan, or task list that has merely been saved to a file.
- Limits of tactical context. Explain why saving prompts and plans does not necessarily give an agent useful context for a later task.
- Structure of strategic specifications. Describe how a structured specification serves as a strategic reference for application behavior across both current and later work.
- Decisions Captured Through Dialogue. Explain how a good specification emerges from back-and-forth between a human and a coding agent, rather than from an unreviewed prompt or a one-way handoff.
- Sufficient Context Without Excess. Explain how to judge the amount of detail a specification needs and how its format can keep the discussion focused.
- Human Reviewable Feature Scope. Explain why specifications must remain manageable for human review and what an unmanageably large spec may indicate.
- Precise Criteria for Success. Explain why verifiable success criteria matter and use the status-filter example to distinguish a weak check from a strong one.
- SDD in the Two Harnesses. Explain where SDD sits in the intent and execution harnesses and how a specification connects them.
- Specification as Implementation Target. Describe how structured dialogue operationalizes an idea and why the resulting specification remains the agent’s target during implementation.
- Phased specification workflow. Explain how SDD separates specification authoring into Discover, Design, and Task before implementation, rather than prompting an agent to code directly from an idea. Distinguish this sequence from waterfall: features are specified incrementally, and specs can be revisited during implementation.
- Discover business context. Describe how Discover turns an initial idea into the feature's What through a human–agent conversation about its users, problem, purpose, scope, and success criteria.
- Design technical approach. Describe how Design uses the established business What to decide the technical How and record the approach and architectural decisions in the spec.
- Task execution breakdown. Explain how Task turns the business context and technical approach into executable units with definitions of done, and what reviewers check in the resulting task list.
- Durable phase artifacts. Explain why the what, how, and tasks phases produce durable artifacts rather than relying on the agent sessions that created them.
- Business and technical separation. Distinguish the What from the How and explain why keeping them separate lets technical architecture change without rewriting stable business context.
- Costs of unclear intent. Explain why more capable coding agents do not eliminate the need to articulate intent, and how unclear direction can make agent use costly.
- Durable specification context. Explain where this section says the return on SDD's upfront investment comes from.
- Vibe coding and course correction. Explain how a high-level prompt can quickly produce working code while leaving the agent to choose unstated behavior, and how follow-up prompts correct choices the developer did not intend.
- Crowded context and compaction. Describe why a long vibe-coding session can enter the “dumb zone,” including how crowded context and compaction can cause earlier decisions to be lost or overlooked.
- Compounding implementation risk. Explain why the initially fast URL-shortener workflow can make later small changes slower and riskier.
- Context debt and manual fallback. Trace how vibe coding loses decision-making context and why that loss can eventually make manual changes seem easier than guiding the agent.
- Plan mode benefits and limits. Explain how plan mode exposes misalignment before implementation and why it does not by itself solve context debt.
- Human Steering Bottleneck. Explain why vibe coding keeps a human in a turn-by-turn correction loop instead of letting an agent execute a larger slice of work independently.
- Cost of Repeated Corrections. Explain why relying on the model to fill gaps and remember corrections makes vibe coding expensive.
- Predictable delivery over initial speed. Explain why predictable delivery can matter more than initial speed, and why vibe coding’s early pace becomes difficult to sustain as an application grows.
- Strategic context for sustainable speed. Explain why deteriorating speed, control, and quality in vibe coding can cast doubt on agentic coding, and distinguish that outcome from what strategic context engineering aims to achieve.
- Durable specifications as execution context. Explain why the vibe-coding pass needed continual human attention and how SDD changes what guides the coding agent: intent is captured in durable specifications before implementation, then supplied as context for implementation and validation.
- Specification readiness. Explain what must be clear before starting a specification and why a vague idea should remain in exploration.
- Vibe coding as a spike. Distinguish exploratory vibe coding from using its output as the delivered product or as a draft specification.
- Purpose of an SDD framework. Explain why the exercise uses an SDD framework and what such frameworks typically package.
- OpenSpec initialization and files. Describe the setup steps and the files that OpenSpec initialization adds to the exercise folder.
- Persistent project context. Explain what to put in openspec/config.yaml for the URL shortener and why it belongs there.
- Propose phase and SDD workflow. Explain how OpenSpec’s Propose, Apply, and Archive phases relate to the SDD workflow, and identify which phase is used to specify a feature before implementation.
- Four connected specification artifacts. Distinguish the purposes of proposal.md, specs/, design.md, and tasks.md, and trace how the earlier artifacts inform the later ones.
- Aligned specification review. Describe how to review generated proposal artifacts, request a missing task, and check that the related files remain aligned before committing.
- Proposal-driven implementation. Describe how the coding agent implements the URL shortener change proposal using OpenSpec's apply proposal skill and its task list.
- Proposal archiving and spec synchronization. Trace what “Sync and archive this proposal” does to the implemented proposal and its specification files.
- Durable context for later changes. Explain how the first feature’s specifications help the coding agent work on a later feature without relying only on code or memory.
- URL expiry change artifacts. Describe how the proposal for making all URLs expire on the 90th day uses existing specifications, and what must be reviewed before applying it.
- Repeated change lifecycle. Trace how the URL expiry change moves from a proposal through implementation and back into the durable specifications.
- Quick code versus sustained alignment. Distinguish generating code quickly from building software with sustained alignment, and describe SDD as the more structured approach.
- Revisable SDD phases. Distinguish SDD’s progression from what to how to tasks from a one-way, phase-gated waterfall process. Explain how discussing architecture can reveal a reason to revisit feature design.
- Reviewable feature specifications. Explain why SDD specifies small features rather than an entire application up front.
- Spec gaps and regeneration. Describe how implementation can reveal a missing detail in a spec and how SDD responds when that gap causes an unintended result.
- SDD adoption as organizational change. Explain why rolling out SDD only as a developer tool, with product handing requirements to developers for conversion into specs, defeats its purpose.
- Conversation and specification roles. Describe how stakeholder and human–AI conversations elicit intent, and how the resulting specification serves both people and an executing agent.
- Specification Time and Execution Throughput. Explain why comparing SDD with vibe coding by time to first generated code misses the longer-term payoff. Describe how a reviewed specification lets an agent implement a feature while the developer works on the next specification.
- Intent Beyond Markdown Artifacts. Explain why producing Markdown files is not the aim of SDD and what a specification must communicate to agents and humans.
- Specification Structure Fits the Work. Describe how the kind of software change affects a specification's format, granularity, and contents, and why tools should support the team's workflow.
What it builds on
- Intent articulation for AI (chapter 1) · Articulating intent for AI.
- What is “Intent”? (chapter 1) · The earlier definition of intent as actionable purpose for a change.
- Intent articulation mechanisms (chapter 1) · Assumes familiarity with approaches for articulating intent.
- Understanding intent (chapter 1) · The need to make intent explicit.
- No mental model of the code (chapter 1) · The problem of lacking a mental model of agent-generated code.
- Fix intent articulation, not the implementation (chapter 1) · The earlier emphasis on fixing intent articulation rather than the implementation.
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.
- Specifications as shared intent: Explain how specifications support intent alignment between humans and agents before implementation and preserve that understanding beyond one interaction. Describe how coauthoring a specification with AI can clarify human intent.
Why it matters: This explains why a specification matters beyond giving an agent instructions for a single task. - Foundations before tool choice: Explain why the chapter recommends understanding SDD's foundational concepts before selecting or adopting a tool.
Why it matters: A grasp of the underlying concepts helps teams judge whether an SDD approach fits their needs.
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.
- Specification as durable context: Explain how an SDD specification makes intent explicit and provides shared, reusable context for humans and AI to produce aligned implementations. Describe what the section means by an artifact.
Why it matters: This definition distinguishes a specification from context that helps only with the current coding task. - Three specification responsibilities: Describe how specification authoring elicits intent through human–AI dialogue, sets implementation constraints and boundaries, and states how to verify that the outcome is aligned.
Why it matters: These responsibilities make intent actionable rather than leaving the agent to infer the solution's boundaries or success criteria. - Durability is not sufficient: Distinguish a complete SDD specification from a prompt, plan, or task list that has merely been saved to a file.
Why it matters: Keeping a file is useful, but the file must preserve intent as guidance for future changes to serve as an SDD specification.
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.
- Limits of tactical context: Explain why saving prompts and plans does not necessarily give an agent useful context for a later task.
Why it matters: Keeping every past instruction is not the same as giving an agent the context it needs now. - Structure of strategic specifications: Describe how a structured specification serves as a strategic reference for application behavior across both current and later work.
Why it matters: An organized specification can orient an agent using relevant details rather than a large dump of past context.
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.
- Decisions Captured Through Dialogue: Explain how a good specification emerges from back-and-forth between a human and a coding agent, rather than from an unreviewed prompt or a one-way handoff.
Why it matters: Dialogue surfaces intent that an agent cannot recover from an unexamined prompt. - Sufficient Context Without Excess: Explain how to judge the amount of detail a specification needs and how its format can keep the discussion focused.
Why it matters: The useful level of detail prevents consequential guesses without burying the work in unnecessary text. - Human Reviewable Feature Scope: Explain why specifications must remain manageable for human review and what an unmanageably large spec may indicate.
Why it matters: A spec that people cannot review cannot reliably serve as their control over the agent's work. - Precise Criteria for Success: Explain why verifiable success criteria matter and use the status-filter example to distinguish a weak check from a strong one.
Why it matters: Verifiable criteria help expose wrong implementations that a vague definition of done would accept.
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.
- SDD in the Two Harnesses: Explain where SDD sits in the intent and execution harnesses and how a specification connects them.
Why it matters: It distinguishes the work of articulating intent from the agent’s work of implementing it. - Specification as Implementation Target: Describe how structured dialogue operationalizes an idea and why the resulting specification remains the agent’s target during implementation.
Why it matters: A specification is useful not merely because it records an idea, but because it gives implementation and verification a clear target. - Specifications as Durable Context: Explain how completed specifications help with later features and why making them navigable is useful.
Why it matters: Keeping specifications accessible lets later work reuse earlier thinking instead of repeatedly rebuilding context.
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.
- Phased specification workflow: Explain how SDD separates specification authoring into Discover, Design, and Task before implementation, rather than prompting an agent to code directly from an idea. Distinguish this sequence from waterfall: features are specified incrementally, and specs can be revisited during implementation.
Why it matters: The sequence gives the agent an articulated intent to work from without treating the spec as unchangeable. - Discover business context: Describe how Discover turns an initial idea into the feature's What through a human–agent conversation about its users, problem, purpose, scope, and success criteria.
Why it matters: A clear business What gives later technical decisions and tasks a purpose to serve. - Design technical approach: Describe how Design uses the established business What to decide the technical How and record the approach and architectural decisions in the spec.
Why it matters: The technical approach connects the business requirement to implementation decisions before work is broken into tasks. - Task execution breakdown: Explain how Task turns the business context and technical approach into executable units with definitions of done, and what reviewers check in the resulting task list.
Why it matters: A reviewed task breakdown gives the agent actionable work that remains tied to the intended outcome and design.
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.
- Durable phase artifacts: Explain why the what, how, and tasks phases produce durable artifacts rather than relying on the agent sessions that created them.
Why it matters: Durable phase outputs keep important decisions available without depending on an agent's memory of an earlier conversation. - Business and technical separation: Distinguish the What from the How and explain why keeping them separate lets technical architecture change without rewriting stable business context.
Why it matters: A team can preserve accumulated business intent while changing how its system is built. - Intent behind technical changes: Explain why a seemingly technical change may still require a statement of intent in the What.
Why it matters: Recording the desired outcome prevents a temporary technical choice from becoming the only expression of the goal.
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.
- Costs of unclear intent: Explain why more capable coding agents do not eliminate the need to articulate intent, and how unclear direction can make agent use costly.
Why it matters: Fast initial output may save little if you repeatedly have to correct what the agent built. - Durable specification context: Explain where this section says the return on SDD's upfront investment comes from.
Why it matters: Reusable context is the payoff offered for reviewing and revising a specification before coding.
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.
- Vibe coding and course correction: Explain how a high-level prompt can quickly produce working code while leaving the agent to choose unstated behavior, and how follow-up prompts correct choices the developer did not intend.
Why it matters: A feature can work while important choices about its behavior were made by the agent rather than by you. - Crowded context and compaction: Describe why a long vibe-coding session can enter the “dumb zone,” including how crowded context and compaction can cause earlier decisions to be lost or overlooked.
Why it matters: Repeated reminders may repair one change while making the session harder to use for the next one. - Lost reasoning across sessions: Explain why a new agent session may produce an uncertain change when it must infer past decisions from code, and why interleaved conversational decisions are hard to reconstruct.
Why it matters: Reading the implementation may not tell you why an earlier choice was made. - Compounding implementation risk: Explain why the initially fast URL-shortener workflow can make later small changes slower and riskier.
Why it matters: The speed of generating the first feature can conceal the cost of safely changing it later.
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.
- Context debt and manual fallback: Trace how vibe coding loses decision-making context and why that loss can eventually make manual changes seem easier than guiding the agent.
Why it matters: It explains why fast initial delivery can make both agent-assisted and manual changes harder later. - Three related forms of debt: Distinguish context debt from context decay and cognitive debt as the section defines them.
Why it matters: These distinctions make clear that an agent forgetting, a developer not understanding, and a project lacking lasting context are related but different problems. - Plan mode benefits and limits: Explain how plan mode exposes misalignment before implementation and why it does not by itself solve context debt.
Why it matters: Reviewing a plan can prevent an immediate wrong implementation without preserving the shared understanding needed for subsequent work.
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.
- Human Steering Bottleneck: Explain why vibe coding keeps a human in a turn-by-turn correction loop instead of letting an agent execute a larger slice of work independently.
Why it matters: It explains why a more capable agent may still fail to give you more independent execution. - Cost of Repeated Corrections: Explain why relying on the model to fill gaps and remember corrections makes vibe coding expensive.
Why it matters: The correction loop consumes money as well as human attention.
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.
- Predictable delivery over initial speed: Explain why predictable delivery can matter more than initial speed, and why vibe coding’s early pace becomes difficult to sustain as an application grows.
Why it matters: A fast first feature is less useful if the team cannot reliably say when later features will arrive. - Strategic context for sustainable speed: Explain why deteriorating speed, control, and quality in vibe coding can cast doubt on agentic coding, and distinguish that outcome from what strategic context engineering aims to achieve.
Why it matters: The limits of vibe coding need not be treated as the limits of every approach to coding with agents.
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.
- Durable specifications as execution context: Explain why the vibe-coding pass needed continual human attention and how SDD changes what guides the coding agent: intent is captured in durable specifications before implementation, then supplied as context for implementation and validation.
Why it matters: The contrast explains why a specification can guide work across features instead of relying on repeated corrections in one conversation.
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.
- Specification readiness: Explain what must be clear before starting a specification and why a vague idea should remain in exploration.
Why it matters: Checking readiness keeps unresolved questions from becoming false commitments in a spec. - Exploration and scope: Explain how an early application or feature attempt helps decide what belongs in the specification.
Why it matters: Exploration can make a specification smaller and more focused, not just more detailed. - Vibe coding as a spike: Distinguish exploratory vibe coding from using its output as the delivered product or as a draft specification.
Why it matters: The purpose assigned to exploratory code determines whether it helps prepare a spec or becomes an accidental delivery method.
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.
- Purpose of an SDD framework: Explain why the exercise uses an SDD framework and what such frameworks typically package.
Why it matters: The framework supplies the setup needed to try SDD without assembling it from scratch. - OpenSpec initialization and files: Describe the setup steps and the files that OpenSpec initialization adds to the exercise folder.
Why it matters: These setup steps put the configuration, artifact location, and agent capabilities in place for the exercise. - Fair exercise comparison: Justify the recommendation to reuse the coding agent and model from the earlier vibe-coding exercise.
Why it matters: Keeping the agent and model the same makes the two exercises easier to compare.
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.
- Persistent project context: Explain what to put in openspec/config.yaml for the URL shortener and why it belongs there.
Why it matters: Putting stable project context in the configuration file saves you from restating it to the agent 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.
- Propose phase and SDD workflow: Explain how OpenSpec’s Propose, Apply, and Archive phases relate to the SDD workflow, and identify which phase is used to specify a feature before implementation.
Why it matters: It keeps specification work distinct from implementation and from closing out an accepted change. - Bounded proposal interview: Describe how the example prompt starts a proposal for the URL shortener’s first slice and asks the agent to clarify its scope before drafting.
Why it matters: Clarifying a bounded feature request gives the proposal a more definite scope before artifacts are drafted. - Four connected specification artifacts: Distinguish the purposes of proposal.md, specs/, design.md, and tasks.md, and trace how the earlier artifacts inform the later ones.
Why it matters: Each artifact answers a different question, while their dependencies let the agent execute tasks grounded in the intended feature. - Aligned specification review: Describe how to review generated proposal artifacts, request a missing task, and check that the related files remain aligned before committing.
Why it matters: Review catches omissions before the agent executes the checklist and helps keep connected artifacts consistent.
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.
- Proposal-driven implementation: Describe how the coding agent implements the URL shortener change proposal using OpenSpec's apply proposal skill and its task list.
Why it matters: The agent can implement from an explicit proposal rather than reconstructing requirements from a conversation. - Verification and durable context: Explain what to check after implementation and why the specification artifacts matter beyond getting the application to run.
Why it matters: A working first slice is useful, but recorded context makes subsequent work less dependent on memory or prior chat sessions. - Proposal archiving and spec synchronization: Trace what “Sync and archive this proposal” does to the implemented proposal and its specification files.
Why it matters: Archiving closes the completed change while keeping the current-behavior specs available to shape later proposals.
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.
- Durable context for later changes: Explain how the first feature’s specifications help the coding agent work on a later feature without relying only on code or memory.
Why it matters: Recorded intent gives a later change more reliable context than code and memory alone. - URL expiry change artifacts: Describe how the proposal for making all URLs expire on the 90th day uses existing specifications, and what must be reviewed before applying it.
Why it matters: Reviewing the change against existing requirements helps catch impacts before the agent implements it. - Repeated change lifecycle: Trace how the URL expiry change moves from a proposal through implementation and back into the durable specifications.
Why it matters: Finishing the cycle keeps the specifications useful as context for the next feature.
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.
- Quick code versus sustained alignment: Distinguish generating code quickly from building software with sustained alignment, and describe SDD as the more structured approach.
Why it matters: This distinction helps explain why SDD’s added structure is worth considering.
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.
- Revisable SDD phases: Distinguish SDD’s progression from what to how to tasks from a one-way, phase-gated waterfall process. Explain how discussing architecture can reveal a reason to revisit feature design.
Why it matters: The structure helps you examine decisions without treating them as irreversible commitments. - Reviewable feature specifications: Explain why SDD specifies small features rather than an entire application up front.
Why it matters: A spec only supports shared understanding if people can meaningfully review it. - Spec gaps and regeneration: Describe how implementation can reveal a missing detail in a spec and how SDD responds when that gap causes an unintended result.
Why it matters: Correcting the source of the deviation lets a new implementation reflect the intended behavior.
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.
- SDD adoption as organizational change: Explain why rolling out SDD only as a developer tool, with product handing requirements to developers for conversion into specs, defeats its purpose.
Why it matters: A new spec format alone will not fix a broken requirements handoff. - Conversation and specification roles: Describe how stakeholder and human–AI conversations elicit intent, and how the resulting specification serves both people and an executing agent.
Why it matters: The value of a spec comes from the shared decisions it captures and makes available to the agent. - Complementary stakeholder expertise: Explain why solo, developer-centric specification misses important context and describe the different knowledge other roles contribute.
Why it matters: Bringing distinct expertise into the spec helps prevent important needs and constraints from being missed.
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.
- Specification Time and Execution Throughput: Explain why comparing SDD with vibe coding by time to first generated code misses the longer-term payoff. Describe how a reviewed specification lets an agent implement a feature while the developer works on the next specification.
Why it matters: It helps you judge SDD by sustained progress rather than the speed of the first code output.
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.
- Intent Beyond Markdown Artifacts: Explain why producing Markdown files is not the aim of SDD and what a specification must communicate to agents and humans.
Why it matters: It keeps attention on whether the specification communicates the right target, rather than on whether a file was produced. - Specification Structure Fits the Work: Describe how the kind of software change affects a specification's format, granularity, and contents, and why tools should support the team's workflow.
Why it matters: A specification process can stay useful across different kinds of work without forcing every change into the same template.
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
- Framework for evaluating tools (chapter 3) · Evaluating tools calls for a basis beyond their differing features and formats.
- Invest where deviation is expensive (chapter 3) · Judging where more specification detail is worth the effort.
- Specifying thoroughly without creating markdown mountains (chapter 3) · Keeping specifications thorough without creating excessive text.
- Intent Loss in Outcome Verification (chapter 3) · Checking whether the outcome matches the specified intent.
- Why specs go stale (chapter 3) · Provides the reason specifications can serve as durable records whose continued accuracy matters.
- Architect shapes the how (chapter 4) · Uses the distinction when discussing technical architecture separately from the product's what.
- Control Authority (chapter 3) · The concept of context debt.
- Exercise Setup (chapter 4) · The problem of losing durable context when decisions remain outside the specification.
Concepts explained in this chapter
- specificationA structured description of software intent, requirements, implementation constraints, and expected outcomes.
- specification-driven developmentA software development approach in which specifications produced through human–AI dialogue guide implementation.
- vibe codingVibe coding is software development guided primarily by natural-language direction and an informal sense that the generated result matches the developer's intent.
- context engineeringContext engineering is the deliberate organization of relevant information so that a participant or system can understand and act on it effectively.
- acceptance criteriaA verifiable condition used to determine whether a requirement or feature has been satisfied.
- course correctionAn adjustment to an agent's instructions or direction in response to an observed mistake, assumption, or undesired result.
- intent alignmentThe state in which humans and agents share an aligned understanding of the intended software outcome before implementation.
- change proposalA documented set of intended modifications to an existing software system, including their requirements and potential impacts.
- durable artifactA durable artifact that records articulated intent to guide implementation.
- ai coding assistantAn AI-powered tool that interprets development instructions and performs coding tasks.
- compactionThe process of replacing earlier interaction content with a shorter summary when an AI agent approaches its context limit.
- context windowA context window is the bounded amount of information an AI model can consider during one interaction.
- dumb zoneA state in which an AI coding agent's crowded or compressed conversational context undermines its ability to work usefully and stay aligned.
- intent articulationIntent articulation is the practice of making a feature's underlying purpose explicit and connecting it to the required approach.
- context debtContext debt is the absence of durable context needed to safely understand, maintain, and evolve software produced through agent interaction.
- OpenSpecA specification-driven development tool that provides workflows and artifacts for proposing, applying, and archiving changes.
- specification authoringSpecification authoring is the structured process of eliciting intent and expressing it as a detailed feature specification.
- intent elicitationIntent elicitation is the process of drawing out a person's intended purpose, requirements, and constraints through interaction.
- plan modePlan mode is an agent interaction pattern in which an AI agent presents its intended implementation approach before modifying code.
- business contextThe set of purpose, scope, user, problem, and success information that explains why a feature or change is needed.
- task phaseThe specification phase in which engineering decomposes design work into executable tasks and defines completion evidence.
- technical approachThe planned way a feature or change fits into an existing architecture and is implemented under its technical constraints.
- execution harnessAn agent harness specialized for independently carrying out tasks and generating implementations or other work products.
- intent harnessA higher-level harness that helps humans and agents articulate intent and produce durable artifacts that guide execution.
- specfallA dysfunctional adoption pattern in which specifications become documents to produce and circulate instead of shared control surfaces for intended software behavior.
- contextInformation supplied to an AI coding agent to guide its understanding and work.
- autonomous actionAn AI agent's ability to complete an implementation task without continuous human intervention.
- intentIntent is the actionable expression of purpose for a specific change, concrete enough to guide implementation and verification.
- implementation constraintAn implementation constraint is a restriction or boundary that limits how a software solution may be designed or built.
- false positiveA result incorrectly judged to satisfy a condition when it does not.
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.
