AI coding agents are now good enough to write most of a feature. The weak point is usually what we ask them for. A one-line prompt leaves hundreds of decisions to the model, so every run produces something slightly different. Spec-driven development fixes this by writing down what to build and why first, then letting the agent work out how. GitHub's open-source Spec-Kit is one of the most popular ways to do it.
Why “vibe coding” breaks down
Prompting an agent until the code “looks right” works for demos. On real business software it tends to fail in predictable ways:
- Hidden assumptions. The model fills gaps (validation rules, edge cases, roles, error messages) with guesses no one reviewed.
- No memory. The reasoning behind the code stays in a chat window that nobody will read again.
- Inconsistent architecture. Each session can pick a different pattern, library or folder layout.
- Hard to review. Reviewers see the code but not the intent, so they can't tell whether it's correct, only whether it compiles.
Spec-driven development makes the specification the main artefact. Code is generated from it, and the spec is kept in the repository next to that code.
What Spec-Kit is
Spec-Kit is an MIT-licensed toolkit published by GitHub. It has two parts:
- a small command-line tool,
specify, that sets up a project with templates and scripts; and - a set of slash commands for your AI agent (Claude Code, GitHub Copilot, Cursor and many others) that guide it through each phase and save the output as Markdown files.
Because everything is plain Markdown in Git, specs get reviewed in pull requests like any other change.
Install and initialise
Spec-Kit is installed with uv, the Python package manager:
# install the CLI
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# create a new project (or run "specify init ." inside an existing one)
specify init leave-portal
During init you choose your AI agent. Spec-Kit then installs the slash commands in that tool's format. Open the project in your agent and the /speckit.* commands are ready to use.
…spec-kit.git@vX.Y.Z) so everyone uses the same templates.The Spec-Kit workflow
The core loop is constitution → specify → plan → tasks → implement, with optional quality gates in between:
| Command | Purpose | Main output |
|---|---|---|
/speckit.constitution | Project-wide principles: code quality, testing, security, performance, UX rules | .specify/memory/constitution.md |
/speckit.specify | Describe what and why: users, stories, acceptance criteria. No tech stack yet. | spec.md |
/speckit.clarify optional | The agent asks targeted questions about gaps and records the answers in the spec | updated spec.md |
/speckit.plan | The how: stack, architecture, data model, API contracts | plan.md, research.md, data-model.md, contracts/, quickstart.md |
/speckit.checklist optional | Custom quality checklists (security, accessibility, etc.) | checklist files |
/speckit.tasks | Break the plan into small, ordered, testable tasks | tasks.md |
/speckit.analyze optional | Cross-check spec, plan and tasks for gaps or contradictions | analysis report |
/speckit.implement | Carry out the tasks and build the feature | code + tests |
For a quick experiment you can run only specify → plan → tasks → implement. For production features we always include clarify and analyze. They catch problems while they're still cheap to fix.
Worked example: leave requests in an HR portal
Let's add a leave-request feature to an existing HR portal built on ASP.NET Core (.NET 10), SQL Server and React + TypeScript.
1. Constitution (once per project)
/speckit.constitution Our principles: clean architecture in .NET 10;
every API endpoint has integration tests; EF Core migrations only (no manual SQL);
React components in TypeScript with accessibility (WCAG 2.2 AA);
no secrets in code; all dates stored in UTC.
2. Specify: what and why
/speckit.specify Employees can request leave (casual, sick, earned) for one or
more days. Managers approve or reject with a comment. Employees see their remaining
balance before submitting. Requests that overlap existing approved leave are blocked.
HR can see all requests and export them monthly.
The agent writes user stories with acceptance criteria and marks open questions, for example “Can half-days be requested?” or “What happens to pending requests if a manager changes?”
3. Clarify
/speckit.clarify
Answer its questions (yes to half-days, pending requests move to the new manager) and the spec is updated. This step catches most of the ambiguity before any code is written.
4. Plan: how
/speckit.plan ASP.NET Core 10 Web API, EF Core with SQL Server, MediatR for
commands/queries, React 18 + TypeScript front end using our existing design system,
notifications through the existing RabbitMQ "notifications" exchange.
5. Tasks, analyse, implement
/speckit.tasks
/speckit.analyze
/speckit.implement
tasks.md lists numbered tasks (T001, T002…) grouped by user story. Tasks that can run in parallel are marked [P], and tests come before the code that makes them pass. /speckit.implement then works through the list. We review each pull request as usual.
What ends up in your repo
.specify/
memory/constitution.md
templates/ …
specs/
001-leave-requests/
spec.md # what & why, stories, acceptance criteria
plan.md # architecture & stack decisions
research.md # options considered
data-model.md # entities & relationships
contracts/ # API contracts
quickstart.md # how to run & verify
tasks.md # ordered, testable tasks
Six months later, a new developer (or agent) can read specs/001-leave-requests and see what was built, why, and how it was tested.
Practical tips
- Keep the spec free of technology. “Store in SQL Server” belongs in the plan, not the spec. Keeping them separate lets you change the stack without rewriting requirements.
- Review the spec harder than the code. A five-minute spec review saves hours of reviewing generated code.
- Keep features small. One spec per feature or user-facing change works far better than one giant spec.
- Write the constitution early and keep it short. It's loaded into every phase, so vague principles create vague output.
- Update the spec first. When requirements change, edit
spec.mdand re-run plan/tasks rather than patching code directly.
When to use it (and when not)
| Great fit | Probably overkill |
|---|---|
| New features with several user stories | One-line bug fixes or copy changes |
| Greenfield products and modules | Throwaway prototypes |
| Teams where several people (and agents) touch the same code | Solo scripts |
| Regulated or audited domains needing traceability | Spikes whose only goal is learning |
If most of your work is changes to an existing system, also look at OpenSpec, which we compare in our OpenSpec and BMAD guide.
How we use it at MD Technosoft
Spec-Kit is one of the main tools in our AI-DLC delivery approach. We write and review constitutions and specs together with clients, then use Claude Code, Cursor or GitHub Copilot to implement against them. Senior engineers review every pull request. Clients end up with working software and documentation that stays in step with the code.
