If you’ve worked with AI coding tools like GitHub Copilot, Claude Code, or Gemini CLI, you’ve likely hit this familiar snag: you explain what you need, the agent spits out clean code that compiles fine, but somehow misses the point of what you actually wanted. “Vibe-coding” gets the job done for quick experiments, but it starts to break down when you’re building production-grade software or modifying established projects. According to GitHub, the problem isn’t the AI’s coding ability — it’s how we’ve been using it. Instead of treating these agents like search engines, we should think of them as detail-oriented pair programmers who are great at spotting patterns but need crystal-clear instructions.
To tackle this challenge, GitHub has released Spec-Kit as an open-source toolkit that brings Spec-Driven Development (SDD) into AI-assisted coding workflows. The project has already gathered over 90,000 stars and 8,000 forks on GitHub, making it one of the fastest-growing developer tooling repos in recent memory.
What is Spec-Driven Development?
Spec-Driven Development flips the traditional software development hierarchy on its head. Instead of specs serving the code, the code serves the specs. The Product Requirements Document (PRD) isn’t just a reference for developers — it’s the blueprint that drives the entire implementation.
In real terms, you start by drafting a structured specification that outlines what you’re building and why, without locking in any particular technology stack. You then hand that document to an AI coding agent as its guiding reference. The spec becomes the single source of truth that AI tools use to generate, test, and verify code. The outcome? Less guesswork, fewer unexpected issues, and better-quality output.
This isn’t the same as traditional “documentation-first” approaches. SDD doesn’t mean writing dense, unreadable requirement documents that collect dust. It’s not about rigid waterfall planning or trying to forecast every detail upfront. And it’s definitely not about piling on bureaucracy that bogs down engineering teams. The spec stays alive — it evolves alongside your requirements rather than getting shelved after the kickoff meeting.
What Spec-Kit Actually Includes
Spec-Kit comes with two main pieces: the Specify CLI, a command-line helper that sets up projects for SDD by pulling down official templates tailored to your chosen coding agent and platform; plus a collection of templates and utility scripts that lay the groundwork for the entire SDD process — defining what a spec should contain, what goes into a technical plan, and how everything gets broken into discrete tasks an AI agent can tackle.
The CLI is built in Python and needs Python 3.11 or newer. The recommended way to install it is through uv:
uv tool install specify-cli --from git+https://github.com/github/[email protected]
specify init After initialization, the agent gains access to a suite of slash commands that map directly to the SDD workflow. The core commands are:
/speckit.constitution— sets up the project’s unchangeable guiding principles/speckit.specify— documents what you want to build, zeroing in on the “what” and “why” without getting into tech stack specifics/speckit.plan— produces the technical implementation plan based on your selected stack/speckit.tasks— divides the plan into a prioritized, dependency-aware task list/speckit.taskstoissues— turns the task list into GitHub issues for tracking and execution/speckit.implement— carries out those tasks using the AI coding agent
There are also three optional commands for added quality assurance and validation:
/speckit.clarify— identifies vague or incomplete areas through structured, step-by-step questioning before a technical plan is drafted (best used before/speckit.planto minimize rework later)/speckit.analyze— performs cross-artifact consistency and coverage checks after/speckit.tasksand before/speckit.implement/speckit.checklist— creates custom quality checklists that verify requirements completeness, clarity, and consistency
One key piece worth highlighting is constitution.md. Within the SDD framework, a constitution document defines a set of firm, non-negotiable principles for a project — things like testing standards, CLI-first mandates, or organizational design system rules. These are defined once and then referenced across every subsequent phase of development.
How to Use GitHub Spec Kit: A Step-by-Step Guide
Spec-Driven Development (SDD) with AI coding agents — from installing the CLI to running your first implementation. Follows the official workflow from the github/spec-kit repository.
Step 1 — Prerequisites
Make sure you have the right tools installed
Before installing the Specify CLI, you need four things on your machine. Spec Kit is cross-platform and works on Linux, macOS, and Windows.
- Python 3.11+ — download from python.org
- uv (recommended) or pipx for package management — install uv from docs.astral.sh/uv
- Git — download from git-scm.com
- A supported AI coding agent — Claude Code, GitHub Copilot, Gemini CLI, Cursor, Windsurf, Codex CLI, or any of the 29 supported integrations
Why uv? It manages tool installations globally, keeps them in your PATH, and makes upgrading easy with uv tool list, uv tool upgrade, and uv tool uninstall. It’s the officially recommended method.
Step 2 — Installation
Install the Specify CLI from GitHub
The only official Spec Kit package is published directly from the GitHub repository. Do not install from PyPI — any package there with the
The same name is not maintained by the Spec Kit team.
uv tool install specify-cli –from git+https://github.com/github/spec-kit.git@vX.Y.Z
pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z
specify version
Visit the Releases page to find the most recent version tag (for example,
v0.8.4). Keep in mind that installing from the main branch could pull in changes that haven’t been officially released yet.Try it without installing: Use
uvx --from git+https://github.com/github/[email protected] specify init to run the tool on the fly with no permanent setup required.Step 3 — Initialize
Get your project started with specify init
Open your project directory and execute specify init. The CLI automatically detects which AI coding assistant you have installed and configures the appropriate folder structure, templates, and commands for you.
specify init my-photo-app
specify init . –integration claude
specify init . –integration codex –integration-options=”–skills”
specify check
Once complete, your project will include a .specify/ folder containing memory/, scripts/, specs/, and templates/ subfolders.
Skills-based setup: Claude Code, Codex CLI, Kimi Code, Devin, and several other assistants use a skills-oriented installation approach — files are placed into agent-specific directories (such as .claude/skills/) rather than slash-command prompt files. To see which installation mode each agent supports, run specify integration list.
Step 4 — Constitution
Define your project’s core principles with /speckit.constitution
The first command to run inside your AI agent is /speckit.constitution. This generates a constitution.md file that captures the non-negotiable guiding rules the agent will follow during every phase that follows. Run this command once for each project.
/speckit.constitution Establish principles centered on:
– Code quality and test coverage benchmarks
– A consistent user experience across every screen
– Performance targets for image-heavy interfaces
– No reliance on third-party image upload services — local storage only
This saves to .specify/memory/constitution.md. Think of these as standing directives — examples include “always use TypeScript,” “never introduce breaking API changes,” or “adhere to our internal design system.”
Step 5 — Specification
Outline what you want to build with /speckit.specify
Describe the application you want to create — concentrate solely on the “what” and “why.” Avoid referencing any technology choices at this point. The agent will generate a spec.md containing user stories and functional requirements.
/speckit.specify Create an application that sorts photos into albums.
Albums are organized by date and can be rearranged through
drag-and-drop on the main page. Albums are never nested within
other albums. Inside each album, photos are displayed in a
grid-style preview layout. Users can rename and remove albums
but cannot delete individual photos from within the album view.
Leave out the tech stack at this stage. Blending “what to build” with “how to build it” too early results in overly restrictive specifications. Technology decisions come in Step 7.
The output is saved to .specify/specs/001-photo-app/spec.md, and a new Git branch is created automatically.
Step 6 — Optional Quality Commands
Refine and verify your spec before moving to the planning stage
Before producing the technical plan, two optional commands help uncover gaps and validate your specification. Both are recommended but can be skipped for quick spikes or experimental prototypes.
/speckit.clarify
A structured, step-by-step Q&A process that records responses directly in a Clarifications section of the spec. This helps reduce rework later. Run this before /speckit.plan.
/speckit.checklist
Produces custom quality checklists that assess whether requirements are complete, clear, and internally consistent — described in the README as “unit tests for English.” Run this after the clarification step.
/speckit.clarify
/speckit.checklist
During the clarification process, the agent may pose questions such as:
- Should albums allow selecting multiple items at once for batch operations?
- Is there a cap on how many photos each album can hold?
- Should drag-and-drop functionality be available on mobile devices, or is it desktop-only?
If you deliberately choose to skip clarification, make sure to inform the agent explicitly — otherwise it may get stuck waiting for missing details before it can move on to the planning phase.
Step 7 — Technical Plan
Define the stack with /speckit.plan
At this point, lay out your technology choices and overall architecture. The agent will produce a plan.md, a data-model.md, a research.md, and a quickstart.md.
/speckit.plan Use Vite with vanilla HTML, CSS, and JavaScript.
Avoid third-party libraries wherever possible. Images are not uploaded
anywhere — instead, their metadata is saved in a local SQLite database
through a lightweight Express backend. For drag-and-drop, rely on the
native HTML5 Drag and Drop API.
Your directory structure after completing this step:
.specify/specs/001-photo-app/
├── spec.md
├── plan.md
├── data-model.md
├── research.md
└── quickstart.md
Review research.md to confirm the right tech stack was selected. If the project involves a fast-evolving framework, have the agent look up the exact installed version before proceeding.
Step 8 — Task Breakdown
Generate tasks with /speckit.tasks and /speckit.taskstoissues
Execute /speckit.tasks to create a tasks.md file containing the complete implementation roadmap. Tasks are grouped by user story, ordered by dependency, and tagged with parallel execution markers.
/speckit.tasks
## User Story: Album Management
– [ ] Create SQLite schema: albums, photos tables
– [ ] [P] Build Express GET /albums endpoint
– [ ] [P] Build Express POST /albums endpoint
– [ ] [P] Implement album rename PUT /albums/:id
## Checkpoint: Validate album CRUD independently
The [P] tag marks tasks that can be worked on simultaneously. Each user story section wraps up with a Checkpoint so you can verify that phase’s functionality works on its own before moving ahead. If desired, you can also turn tasks into GitHub Issues:
/speckit.taskstoissues
Step 9 — Cross-Artifact Analysis
Validate consistency with /speckit.analyze
Once tasks have been generated but before starting implementation, run the optional /speckit.analyze command. It checks for consistency and coverage across the spec, plan, data model, and tasks to make sure everything lines up.
/speckit.analyze
The agent will call out issues such as:
- A user story in
spec.mdthat has no matching task intasks.md - The plan referencing a database table that isn’t defined in the data model
- A behaviour outlined in the spec that has no task assigned to implement it
This is a read-only command — it generates a findings report without altering any files. Resolve any flagged issues before running /speckit.implement to avoid cascading problems during code generation.
Step 10 — Implementation
Execute with /speckit.implement
With all artifacts ready, run /speckit.implement. The agent first confirms that constitution.md, spec.md, plan.md, and tasks.md are all present, then carries out the tasks in sequence — honoring dependencies and [P] parallel markers.
/speckit.implement
Local CLI tools must be installed. The agent will invoke commands like npm, dotnet, or python directly on your machine. Ensure all required runtimes are set up before executing this command.
Working on a new feature? You can skip /speckit.constitution (it only needs to run once per project) and begin with /speckit.specify for each additional feature.
✅ Full Spec Kit Workflow — Quick Reference
- Install:
uv tool install specify-cli --from git+https://github.com/github/[email protected] - Init project:
specify init--integration - Establish project principles:
/speckit.constitution— execute once at the start of each project - Draft the spec:
/speckit.specify— outline what you want to build, leaving the how for later - Fill in ambiguities:
/speckit.clarify(optional, but wise to run before planning) - Verify the spec:
/speckit.checklist(optional, best done after clarifying) - Create the plan:
/speckit.plan— define the technology stack and system architecture - Divide into tasks:
/speckit.tasksplus the optional/speckit.taskstoissues - Assess consistency:
/speckit.analyze(optional, run after tasks and before implementation) - Start building:
/speckit.implement
