2 Writing Your First Specification
This chapter covers
- Defining specifications
- How SDD works
- Why vibe coding creates context debt and unpredictability
- Writing a URL shortener spec
- Common SDD misconceptions
The core philosophy of SDD is to establish intent alignment between humans and agents before implementation begins, with specifications facilitating the dialogue and acting as durable artifacts that preserve that understanding beyond the current interaction. In addition to helping agents understand our intent, coauthoring the specification with AI deepens our understanding of what we are trying to accomplish. This becomes even more important as we move from individuals interacting with agent counterparts to improve personal productivity to entire teams interacting with agent swarms that involve complex collaboration patterns.
SDD tools vary widely in their approach and in the opinions they bring to the table. Some tools treat specs as a small set of markdown files guided by lightweight agent instructions. Others extend the idea across discovery, design, tasking, implementation, review, and multi-agent orchestration. While this variety is useful, it can also make it difficult to choose a tool or approach.