Chapter 2 · Spec-Driven Development in Depth · Lesson 2.3
Spec Kit in Practice
The parts that make Spec Kit work in the real world - the analyze quality gate, shaping it to your team, and knowing when it is just overhead.
- Chapter 0 · Sprint Zero
- Chapter 1 · The ratchet & the practice loop
- 2.1 · The SDD mindset & the trio
- 2.2 · Spec Kit, end to end
- 2.3 · Spec Kit in practice
- 2.4 · OpenSpec & agent-skills
- 2.5 · Choosing & adopting
Lessons 2.1 and 2.2 walked the full Spec Kit chain - constitution, specify, plan, tasks, implement. This lesson is about the parts that decide whether that chain actually pays off on real work: a quality gate you run before writing code, ways to shape the tool to your team, and an honest read on when the whole thing is too heavy. All of it is still spec-driven development - the spec is the source of truth - just applied with judgement.
The analyze gate
Spec Kit gives you a slash command, /speckit.analyze, that you run after tasks and before implement. It is read-only - it looks at your artifacts and reports, but it never edits a single file.
/speckit.analyze before implementation. It reviews the spec, plan, and tasks together, flags inconsistencies, gaps, and any breach of your constitution (the project's non-negotiable rules), and makes no changes.
GitHub Spec Kit docs
Why it matters: the gate catches logical gaps while they are still cheap words on a page. A task that contradicts the spec, a plan step with no matching task, a rule in the constitution nobody honoured - each one is a bug you would otherwise meet as a runtime failure once the agent has written the code. Reading three documents against each other is exactly the kind of consistency check a model is good at and a tired human skips.
Making it fit
Spec Kit is not a take-it-or-leave-it black box. It is built to be reshaped without forking the project (GitHub Spec Kit).
- Agent-neutral - the same workflow runs across 30+ coding agents (Claude Code, Copilot, Cursor, Gemini, Codex, and more), and there is a lighter "skills mode" if you do not want the full CLI ceremony.
- Extensions - add your own slash commands and templates on top of the built-in set.
- Presets - override the built-in templates outright, for example a compliance-oriented spec format or your org's house standards.
So when the default spec shape does not match how your team works, you bend the tool - you do not abandon it or copy the whole repo to hack on it.
When it shines vs when it is overhead
Spec Kit shines on the work it was built for: production systems, team codebases, and long-lived projects where getting the decisions right up front is worth real ceremony. It becomes friction elsewhere, and it is worth naming exactly where (Microsoft for Developers):
- Token cost - expect roughly 20-40% more tokens, because the agent re-reads the spec, plan, and tasks on each turn.
- CLI churn - the tool moves fast. Version 0.10 removed the
--aiflag family, which broke older scripts and tutorials that still assumed it. - Brownfield mess - on tangled existing systems the structure tends to produce volume (lots of documents) rather than fidelity (more correct code).
- Exploration - the phased gates fight research-heavy, exploratory work where you do not yet know enough to write a spec.
- No task parallelization yet - tasks run in sequence, so it will not fan work out across agents for you.
A fair caveat
Gojko Adzic, a long-standing voice on specification and testing, frames spec-driven development as a logical evolution of how we work with agents - but also a potential overcorrection. His worry: all this structure risks quietly reintroducing some of the rigidity that agile methods were built to escape. That is not a reason to skip Spec Kit. It is a reason to notice when the process starts serving itself instead of the code.
Back to the ratchet
This is the same lesson as the ratchet from Chapter 1, seen from the other side. There you added a rule only after a real failure earned it. Here you keep only the Spec Kit ceremony that earns its place - the analyze gate on production work, presets where your team needs them - and you drop the rest on throwaway or exploratory jobs. A spec framework is still a harness you tune, not a ritual you obey.
Check yourself
You run /speckit.analyze -
Analyze is a read-only gate you run after tasks and before implement. It reviews the spec, plan, and tasks for gaps and constitution breaches, and changes nothing itself - so logical gaps get caught before they become runtime failures.
Presets in Spec Kit -
Extensions add new commands and templates; presets override the built-in ones (say a compliance-oriented spec format). Both let you shape Spec Kit to your team without forking the project.
Spec Kit is the worst fit for -
Its phased gates and per-turn token cost pay off on production, team, and long-lived work - but they fight fast, exploratory, research-heavy jobs where you do not yet know enough to write a spec.
Do this now (10 min)
Take the spec you generated in Lesson 2.2 and run /speckit.analyze on it. Read what it flags - the inconsistencies or gaps you would otherwise have hit at implement time. That list is the gate earning its place.
Go deeper
Primary source (read this): the GitHub Spec Kit docs - the reference for the analyze gate, extensions, and presets.
Secondary: Microsoft for Developers, "Diving into Spec-Driven Development with GitHub Spec Kit" - a hands-on walkthrough with the real trade-offs.
Wisdom (test it on people): r/ChatGPTCoding - practitioners arguing over when Spec Kit's ceremony is worth it and when it is not.