Spec Kit: from testable intent to traceable acceptance
A Spec Kit quickstart that produces testable requirements, not more vague prose
Practice a small reading-list specification with acceptance scenarios, explicit unknowns and a pre-implementation consistency review.
What you will learn
- Describe the observable result first
- Resolve uncertainty before it becomes architecture
- Inspect consistency before implementing
Before you start
- Basic requirements, Git and testing concepts
- Understanding of local development versus application deployment
Trace a small feature from intent to evidence and distinguish workflow contracts from verified behavior.
Key takeaways
- An acceptance scenario needs an observable result.
- Unresolved scope decisions should not be disguised as technical defaults.
- Analyze findings before approving remediation.
Describe the observable result first
Use a disposable learning project and a synthetic reading list containing only public example titles. The first journey is saving an item and seeing it after restarting the application. State what happens for duplicate items and invalid input. Do not choose a database in the requirement merely because a familiar framework comes to mind.
The template separates user stories from functional requirements and success criteria. An acceptance scenario needs an initial state, an action and an observable result. “Make saving reliable” is too vague; “after saving one valid item and restarting, the list contains that item once” gives the reviewer something concrete to verify.
Resolve uncertainty before it becomes architecture
Record unknowns explicitly, such as whether the list is device-local or shared across accounts. This decision changes privacy, synchronization and deployment requirements. Ask for clarification before the technical plan if the choice would materially alter the product; a generated assumption is not equivalent to a user decision.
In the chosen integration, use the installed equivalents of constitution, specify, clarify where needed, plan and tasks. Command presentation varies by integration, so do not paste an unfamiliar slash-command spelling into the operating-system shell. This article describes the workflow without claiming a live agent session was run.
Inspect consistency before implementing
The analyze command is intended to compare spec.md, plan.md and tasks.md after task generation. Look for uncovered requirements, tasks with no clear purpose, contradictory storage decisions and acceptance criteria that cannot be tested. Its report should point to a concrete artifact location and explain the mismatch.
Review the report before authorizing edits. The core analysis contract is read-only, but the command also describes extension hooks and invokes a prerequisite helper; those surrounding mechanisms need their own side-effect review. Generating a report is not the same as approving every proposed remediation.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Write one save-and-restart scenario.
- 2
Decide duplicate behavior and document unknowns.
- 3
Map the requirement to a plan decision and task.
- 4
Review consistency before implementation.
Copy-ready example
{
"synthetic": true,
"given": "one valid public example item",
"when": "save and restart",
"then": "the item appears exactly once",
"unknown": "device-local or account-shared",
"implementationAuthorized": false
}Frequently asked questions
Should a specification choose the database immediately?
Only if that is an actual constraint; otherwise put technical choices in the plan.
Will analyze automatically apply its recommendations?
Its core contract requires read-only reporting and separate approval for remediation; inspect extensions and helpers independently.
Sources
- Spec Kit / templates/spec-template.mdSource checked 2026-09-14
- Spec Kit / templates/commands/analyze.mdSource checked 2026-09-14
- Spec Kit / README.mdSource checked 2026-09-14