Spec-Driven Development

Spec-Driven Development with GitHub Spec-Kit: A Practical Guide

Stop prompting until it works. Here's how GitHub's Spec-Kit turns a feature idea into a constitution, a spec, a plan and a task list before an AI agent writes any code, with a worked .NET + React example.

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.

Tip: pin a released version in team projects (…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:

CommandPurposeMain output
/speckit.constitutionProject-wide principles: code quality, testing, security, performance, UX rules.specify/memory/constitution.md
/speckit.specifyDescribe what and why: users, stories, acceptance criteria. No tech stack yet.spec.md
/speckit.clarify optionalThe agent asks targeted questions about gaps and records the answers in the specupdated spec.md
/speckit.planThe how: stack, architecture, data model, API contractsplan.md, research.md, data-model.md, contracts/, quickstart.md
/speckit.checklist optionalCustom quality checklists (security, accessibility, etc.)checklist files
/speckit.tasksBreak the plan into small, ordered, testable taskstasks.md
/speckit.analyze optionalCross-check spec, plan and tasks for gaps or contradictionsanalysis report
/speckit.implementCarry out the tasks and build the featurecode + 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.md and re-run plan/tasks rather than patching code directly.

When to use it (and when not)

Great fitProbably overkill
New features with several user storiesOne-line bug fixes or copy changes
Greenfield products and modulesThrowaway prototypes
Teams where several people (and agents) touch the same codeSolo scripts
Regulated or audited domains needing traceabilitySpikes 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.

  • Spec-Kit
  • Spec-Driven Development
  • Claude Code
  • GitHub Copilot

Sources & further reading

Bring spec-driven, AI-assisted delivery to your team

We can run a pilot Bolt with your team, or embed Forward Deployed Engineers who already work this way.