Part IV: Specification Engineering
The Most Important Skill in SDD
In Spec-Driven Development, the specification is the source of truth. AI agents generate code from specifications. Tests validate against specifications. Architecture emerges from specifications. The entire methodology depends on one foundational skill: writing specifications precise enough to generate working systems.
This part teaches the craft of specification engineering — the discipline of writing functional, behavioral, and non-functional specifications that are unambiguous, testable, and executable by both humans and AI.
What You Will Learn
Chapter 9: Anatomy of a Perfect Specification
A specification is not a wish list or a rough sketch. It is a complete contract that defines what the system must do, how it must behave, and what it must not do. This chapter breaks down the anatomy of a perfect specification into ten essential components: problem statement, user journeys, functional requirements, non-functional requirements, acceptance criteria, edge cases, constraints, dependencies, observability, and security requirements.
You will learn each component through detailed examples, walk through a complete "Password Reset" specification, and practice writing a full "Team Invitation" feature specification step-by-step. You will also learn how AI uses each section differently, recognize common anti-patterns that undermine specification quality, and apply a scoring rubric to evaluate your own specifications.
Chapter 10: Behavioral Specifications
Behavioral specifications transform acceptance criteria into executable scenarios. Using the Given/When/Then format (BDD/Gherkin), you write specifications that serve simultaneously as documentation and as test definitions. This chapter covers scenario structure, happy paths, error paths, edge cases, and Scenario Outlines for parameterized testing.
You will write behavioral specs for a complete "Shopping Cart" feature, learn to translate acceptance criteria into Gherkin scenarios, and integrate with test frameworks like Cucumber, Playwright BDD, and Behave. You will also learn to avoid the anti-pattern of scenarios that test implementation rather than behavior.
Chapter 11: Non-Functional Specifications
Functional requirements define what the system does. Non-functional requirements define how well it does it. Performance, security, scalability, reliability, and observability — these quality attributes determine whether a system succeeds in production or fails under load.
This chapter teaches you to write measurable non-functional requirements: not "fast" but "p95 latency < 200ms"; not "secure" but "all API keys encrypted at rest with AES-256." You will write NFRs for the running collaboration platform project, understand the relationship between NFRs and constraints, and learn how AI agents use NFRs to make architectural decisions.
The Connection
The three chapters form a progression:
- Chapter 9 establishes the structure — the ten components that make a specification complete and precise.
- Chapter 10 adds behavioral rigor — the Given/When/Then format that makes specifications executable as tests.
- Chapter 11 extends the specification into quality attributes — the non-functional requirements that govern performance, security, and reliability.
Together, they give you the complete specification engineering toolkit. By the end of Part IV, you will be able to write specifications that AI agents can implement without guessing, that test frameworks can execute automatically, and that stakeholders can validate against measurable criteria.