Ask Claude, Codex, or Gemini to “build me an ERP with auth, billing, a dashboard, and a mobile app” and you’ll get something that half works and is architecturally cursed in ways you won’t notice until week three. The model isn’t bad at writing code. It’s bad at simultaneously inventing the product, the architecture, and the implementation order while also writing the code. GitHub’s Spec Kit exists to split those apart.
The workflow
Spec Kit is a CLI plus a set of slash commands that turn one big ambition into a chain of documents, each one feeding the next and each one small enough to actually review:
/speckit.constitution— the non-negotiable rules for this project: testing bar, layering, what the agent must not do/speckit.specify— what you’re building and why, no tech stack yet/speckit.clarify— the agent asks about the gaps instead of quietly guessing and moving on/speckit.plan— now the stack and architecture/speckit.tasks— the plan cut into small, ordered, independently reviewable units/speckit.implement— code, one task or one small phase at a time
Every step writes a markdown file into specs/<feature>/. That’s the part that actually matters: the spec, the plan, and the task list persist across sessions instead of living in a chat window that turns to mush after forty messages of “no, not like that.”
Installing it
|
|
It also integrates with Codex CLI, Gemini CLI, Cursor, and Google Antigravity, though the setup isn’t identical across them. Codex mounts the workflow as skills under .agents/skills and calls them $speckit-* instead of slash commands. Cursor’s integration key is cursor-agent, not cursor. Antigravity’s is agy. Get the key wrong and specify just doesn’t wire anything up, with no obvious error to point you back at the typo.
What it actually looks like in practice
The most convincing account I’ve seen of running this end to end is an engineer who pushed a legacy ASP.NET premium-calculator app through it into Spring Boot. Reverse-engineer the business rules into a doc first, write a constitution pinning down package layout and an 80% test-coverage bar, spec the first feature, clarify seven real ambiguities the spec had glossed over (is the insurance-type match case-sensitive, does a “Metro” surcharge apply twice if the word shows up twice in the address), plan, then land on 38 generated tasks split into 7 implementation phases so the model was never asked to write the whole service in one pass.
It mostly worked. Coverage cleared the bar. Two tests failed on the first run (a rounding bug and a rule-ordering bug), fixed with one more prompt pointed straight at the failing assertions. The code review after that found exactly what you’d expect from AI output that technically passes: validation layers stacked on validation layers, a domain model that’s mostly a data bag, and tests that only ever exercise the happy path.
The catch
None of this replaces reading the output. The constitution does more real work than any other file in the pipeline. A vague one produces a technically-passing, structurally mediocre service no matter how many clarification rounds run before it. And the whole method falls apart if you skip from spec straight to /speckit.implement: the gap between what read fine in prose and what breaks in code is exactly what clarify and plan review exist to catch.
Spec Kit doesn’t make the model smarter. It gives it something better than a prompt to work from, and gives you something to review before the code exists instead of after.