SDD 01 - Foundations
SDD Learning · Next: Lab
Level 1 · Understand. Read this page at your own pace. You have passed the level when you can answer the four questions at the end.
Spec-driven development makes the intended behavior explicit before implementation and keeps that specification involved in planning, testing and review. The specification is a maintained agreement that people and coding agents can consult when the conversation is no longer available.
For this learning path, a useful specification answers four questions: what should happen, what must remain compatible, what is excluded, and how will we recognize success?
Read the colors
One color means one thing in every diagram of this Learning. In the picture above the request is cyan because it is intent, the requirement and its scenario are blue because they are the contract, and the check is green because it produces evidence. The first six colors are also the six levels of the path, in order.
Four things to keep separate
| Item | Answers | Example |
|---|---|---|
| Request | What outcome do we want? | Make the Markdown index machine-readable |
| Specification | What behavior must be true? | JSON contains sorted file/title records; default text output is unchanged |
| Technical plan | How will we implement and check it? | Reuse collection logic, add an argparse option and exercise the CLI through subprocess tests |
| Evidence | What did we actually observe? | A test run on the final code produced the expected records and passed the compatibility checks |
The implementation plan can change while the user-visible contract remains stable. If the contract changes, update the related scenarios and tests explicitly.
Make the contract observable
Compare these requirements:
| Weak | Useful for this exercise |
|---|---|
| JSON output should be good | JSON is an array of objects containing exactly the string fields file and title |
| Keep compatibility | Running without a format option produces byte-for-byte identical text output |
| Handle errors properly | Unknown formats and missing directories return nonzero status, useful stderr and empty stdout |
A scenario makes the requirement concrete. Given two known Markdown files, selecting JSON must return exactly their records in filename order. Given an empty directory, it must return an empty array. These are examples that can become executable checks.
Do not accidentally specify irrelevant detail. JSON whitespace and object key order are not part of this exercise's contract; the parsed values and array order are.
The feedback loop
Two failures need different responses. If the program changes text output despite the accepted requirement, fix the implementation. If the requirement omitted an important behavior, agree on the missing decision and update the contract and tests together.
Validation, verification and acceptance
| Activity | Checks | Does not establish by itself |
|---|---|---|
| Specification validation | Structure, consistency and completeness of the documents | Correct runtime behavior |
| Application verification | Observed behavior against selected expectations | That the expectations capture everything the user needs |
| Human acceptance | The result and evidence against the intended outcome | A mathematical proof of all possible behavior |
An agent's statement that the task is finished belongs in the review conversation. It does not replace the commands, results and limitations behind that statement.
What the frameworks add
Matt Pocock Skills supplies composable engineering workflows and keeps project knowledge durable. Spec Kit structures the feature artifacts and their handoffs. OpenSpec emphasizes current contracts and proposed deltas. BMAD Method organizes planning depth and delivery perspectives. Superpowers supplies engineering disciplines for design, testing and verification. Their capabilities overlap.
The lab has a route for each of the five, and Matt Pocock Skills is the baseline route you walk first. The skill to transfer to another framework is the relationship between the accepted requirement, implementation task and evidence.
Level 1 check
Answer these before you look at the answers:
- Is “use Python's json module” a requirement or a technical choice? It is a technical choice unless the project's constraints explicitly require it.
- Does a valid spec file prove the JSON output works? No; run the application checks.
- If a new feature breaks the old output, can it still satisfy this exercise? No; compatibility is part of the contract.
- If tests pass and the agent edits the code again, what should happen? Rerun the relevant checks on the new revision.
Level 1 complete. You can tell a request, a contract, a plan and evidence apart. Level 2 is in the lab.
For background, see the Spec Kit quickstart and OpenSpec artifact model.