Dev ToolsArticle
GitHub's open toolkit turns intent into a living contract so coding agents stop freelancing your architecture.
AI coding agents got good enough that teams started shipping on vibes. Describe a feature, accept a blob of plausible code, patch the gaps. That works for a prototype. It falls apart when the backend engineer, the frontend, and the product owner each assumed a different meaning of "notification preferences," and nobody wrote the assumption down until the rewrite was already expensive.
Spec Kit is GitHub's open-source answer: make the specification the executable source of truth, and treat generated code as something you can regenerate. Spec-driven development (SDD) is not a return to waterfall. It is structured steering for literal-minded pair programmers that still need unambiguous instructions.
Specs as contracts, not scaffolding #
For decades, specs were disposable. You wrote them, built the code, and the code became the real product. SDD flips that. The "what" and "why" live in living documents that evolve with the project. Technical choices stay separate until you deliberately inject them.
That separation is the useful part. A clean product-level spec can drive multiple implementation variants (different languages, different UI mocks via something like a Figma MCP server) without untangling a hybrid PRD full of stack decisions. Code is still reviewed and still ships. It just stops being the only place where requirements hide.
GitHub positions this against "vibe coding": agent output that looks right, fails to compile, or solves the wrong problem because the prompt was a search query, not a contract. Spec Kit does not make models deterministic. It reduces how much of the variance comes from missing shared context.
The four-phase loop (plus guardrails) #
Spec Kit is scaffolding, not a product. A specify
CLI bootstraps templates and agent-facing prompts; slash commands (or skills, depending on the agent) drive the loop. Supported integrations include GitHub Copilot, Claude Code, Gemini CLI, and Codex CLI.
Typical flow after install:
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.12.11
specify init my-project --integration copilot
cd my-project
Then, in the agent:
Constitution(/speckit.constitution
) — non-negotiable project principles: testing bar, UX consistency, performance rules, banned patterns. Run once; it anchors later work.Specify(/speckit.specify
) — user journeys, outcomes, success criteria. Deliberatelynotthe tech stack. Focus on who uses it and what must be true.Plan(/speckit.plan
) — now inject stack, architecture, compliance, legacy constraints. Ask for plan variants if you want alternatives side by side.Tasks(/speckit.tasks
) — small, isolatable work units (think "registration endpoint validates email format," not "build auth").Implement(/speckit.implement
) — agent executes tasks; you review focused diffs, not thousand-line dumps.
Optional clarify/analyze steps exist to surface underspecified areas and check alignment before code. Init lays down .specify/
(memory, templates, scripts) and agent prompt material (for Copilot, under .github/
). Extensions, presets, and role-based bundles let teams customize without forking the whole idea.
The checkpoint discipline matters more than the folder layout. You do not advance a phase until the current artifact is good enough. The agent generates; the human verifies.
What this means in a real workflow #
Who should care. Teams using agents on existing codebases, multi-person features, or anything with compliance, performance, or architectural constraints. Solo weekend tools can stay on pure chat. The ceremony costs real minutes; it pays off when misaligned assumptions cost sprints.
What it replaces. Ad-hoc system prompts, scattered Notion PRDs nobody reads, and the habit of treating the repo as the only requirements store. It competes with homemade agent playbooks and with "just paste the ticket into Copilot." It does not replace code review, tests, or product judgment.
Adoption path that is not theater.
- Start on one feature branch in an existing repo (
specify init --here
), not a greenfield rewrite of process. - Write a constitution that matches how you already ship: real test policy, real stack pins, real "never do X" rules. Vague constitutions produce vague plans.
- Keep specify-phase language non-technical on purpose. If SQLite and Vite leak into the first prompt, you have already coupled the contract to one design.
- Treat tasks as the unit of review. If a task cannot be implemented and checked in isolation, split it before
/speckit.implement
. - Expect iteration: refine the spec when the agent misses an edge case, the same way you refactor code. Specs that never change are just bureaucracy.
Trade-offs. Up-front writing is slower than a one-shot prompt. Bad specs amplify confidently into bad plans. Agents still hallucinate inside a task boundary. Teams that refuse to stop and critique each phase will generate prettier process theater and the same mess. Multi-variant experiments from one spec are powerful only if someone actually compares outcomes.
If it pans out. Spec Kit is still framed as an experiment in making LLM-steered work more deterministic. Worth attention now if agents already write a material share of your diffs and quality variance is the pain. Watch whether the templates stay thin enough to customize, whether constitution/memory actually constrain later phases in practice, and whether task granularity stays reviewable as features grow. Skip deep investment if your work is throwaway or your org will not enforce the checkpoints.
Where SDD sits in the AI stack #
Spec Kit sits above the model and the IDE agent. It is process infrastructure: versioned intent, explicit tech injection, task decomposition. That is closer to "TDD for the human–agent boundary" than to a new framework. Prior art includes PRDs, ADRs, and every internal "how we use Copilot" doc. The difference is packaging those ideas as agent-native commands and repo-local templates so the same artifacts feed generation, not just humans.
The honest limit: specifications do not remove the need for taste. They move negotiation earlier, when changing direction is cheap. If the constitution is wrong, or the specify prompt papers over product ambiguity, the agent will faithfully implement the wrong thing faster.
Bottom line #
Spec Kit is a credible packaging of a simple claim: coding agents behave better when intent, constraints, and work units are explicit and reviewable before code. Use it when shared context is the bottleneck. Keep vibe coding for sketches. The win is not magic determinism; it is fewer expensive surprises when the model does exactly what you failed to say.
Sources & further reading #
github/spec-kit— github.com - Diving Into Spec-Driven Development With GitHub Spec Kit - Microsoft for Developers— developer.microsoft.com - Spec-driven development with AI: Get started with a new open source toolkit - The GitHub Blog— github.blog - What's The Deal With GitHub Spec Kit | Den Delimarsky— den.dev - GitHub Spec-Kit: From Vibe Coding to Spec-Driven Development - DEV Community— dev.to
Priya Nair· AI & Developer Experience Writer
Priya covers AI frameworks, developer productivity tooling, and the startup ecosystem across South and Southeast Asia, bringing a researcher's rigour and a practitioner's empathy to every story. She is deeply sceptical of benchmarks and asks hard questions so her readers don't have to.
Discussion 0 #
No comments yet
Be the first to weigh in.