Spec Kit: from testable intent to traceable acceptance
Spec Kit explained: keep requirements, implementation and acceptance connected
Understand the Specify CLI, agent instructions and persistent feature artifacts without mistaking a specification for a compiler or a release certificate.
What you will learn
- Three kinds of work, not one magic generator
- Use the artifacts to explain why code exists
- Choose a bounded first feature
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
- CLI setup, agent judgment and human acceptance are different responsibilities.
- Persistent artifacts connect intent to implementation evidence.
- A completed checklist is not proof of a deployed working feature.
Three kinds of work, not one magic generator
At revision d848fb4, GitHub Spec Kit combines the Specify CLI, agent-facing instructions and templates for feature artifacts. The CLI installs and configures a workflow; the coding agent interprets its commands; people still decide requirements and accept the result. The toolkit is not itself a replacement model or a hosted application platform.
Its spec-driven approach makes intent durable in spec.md, technical choices in plan.md and executable work items in tasks.md. Calling specifications executable describes the intended development process, not a guarantee that arbitrary prose compiles deterministically into correct software. A fluent specification can still contain a bad assumption.
Use the artifacts to explain why code exists
The standard progression establishes project principles, specifies user outcomes, plans implementation, creates tasks, implements and checks convergence. For a small reading-list feature, the specification could require restoring saved items after restart; the plan selects storage; tasks name the changes and tests needed to satisfy that requirement.
This creates a reviewable chain from user need to implementation evidence. A checked task is only one observation in that chain. It does not independently prove that the behavior works, that all acceptance scenarios were exercised or that the deployed application contains the same revision.
Choose a bounded first feature
Start with one independently useful user journey, not an entire product specification. Preserve explicit non-goals and unresolved questions. The supplied spec template asks for prioritized stories, independent tests, acceptance scenarios, functional requirements, measurable outcomes and assumptions. Placeholder headings are not completed requirements.
This series reads seven pinned files, including analysis and convergence commands, installation guidance and two script entry points. A separate synthetic append-contract model is tested. We did not install Specify, run a coding agent, execute upstream scripts or benchmark delivery speed.
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
Select one independently useful journey.
- 2
State observable outcomes and non-goals.
- 3
Trace requirements through plan, tasks and verification.
Copy-ready example
{
"example": true,
"feature": "local reading list",
"requirement": "saved items survive restart",
"taskChecked": false,
"behaviorVerified": false,
"productionVerified": false
}Frequently asked questions
Is Spec Kit a language model?
No. It supplies tooling and workflow material for supported coding-agent integrations.
Does Converged mean the product is already deployed?
No. Review, delivery and production verification remain separate.
Sources
- Spec Kit / README.mdSource checked 2026-09-14
- Spec Kit / templates/spec-template.mdSource checked 2026-09-14
- Spec Kit / templates/commands/converge.mdSource checked 2026-09-14