SDD: make the specification executable
Keep intent, implementation tasks, and acceptance evidence connected as the software changes.
BY THE END, YOU CAN
- Separate a behavioral specification from an implementation plan
- Trace requirements through tasks and acceptance tests
- Update a living specification when evidence changes the design
Diagram description: Spec → Plan; Plan → Tasks; Tasks → Code; Code → Acceptance tests (checked by); Acceptance tests → Spec (trace to)
Clarify the promise before the mechanism
Here SDD means spec-driven development: a reviewed statement of behavior guides planning, implementation, and verification.
For Relay cancellation, “cancel a job” is incomplete. Can running jobs be cancelled? Who may request it?
What happens if cancellation races with a worker claiming the job? Write an initial specification around user outcomes, examples, constraints, and non-goals. Resolve the ambiguities with the people who own the behavior.
Number acceptance criteria: AC-1 might require an authorized cancellation of a pending job to prevent a subsequent worker claim. Define the race precisely before choosing a mechanism.
Connect the plan to observable evidence
The plan explains how to meet that promise: state transitions, storage transaction, API response, and compatibility.
Tasks divide the plan into reviewable work. Trace AC-1 to the state-transition task and a test that tries to claim a cancelled job. Add a concurrency test for the chosen race rule; a sequential example cannot establish it.
Keep acceptance expectations grounded in the specification, rather than copying whatever the generated implementation does. Ask an assistant to find contradictions across the spec, plan, tasks, and tests. A reviewer must still decide whether the contract is correct.
Use living documents, scaled to risk
GitHub Spec Kit provides one concrete workflow for specification, clarification, planning, tasks, and implementation checks.
SDD does not require that tool or a large document set. A tiny pure function may need a few criteria beside its tests; cancellation with concurrency and permissions needs deeper review. When investigation changes an assumption, update the spec, decision record, and affected tests together.
Preserve the reason for a consequential change. Generated documents and checked boxes do not guarantee completeness, security, or good architecture. Close the loop by comparing the implemented behavior with the original user need.
COMMON FAILURE MODE
Treating a generated specification as approved truth, or silently changing acceptance tests to match code that violates the intended contract.
TRY IT YOURSELF
Write a compact Relay cancellation specification with three acceptance criteria, a non-goal, and an unresolved race question. Map each criterion to a task and a test with an observable expected outcome.
Make the call in the laboratory.
The two-question checkpoint, your notes, and your saved progress are in the laboratory. Free, with no account.
Open in the laboratory ↗CONNECT IT TO RELAY
In the AI delivery project, specify duplicate reuse, conflicting payload rejection, validation before reserving a key, and a stable payload snapshot. Map criteria to tasks and tests. State the prototype’s concurrency limit and the atomicity a production design would need.