How to Use GitHub Spec-Kit for Spec-Driven Development with AI Coding Agents

By • min read

Introduction

If you've used AI coding agents like GitHub Copilot, Claude Code, or Gemini CLI, you've likely experienced this: you describe what you want, the agent produces code that looks correct and compiles, but it subtly misses your intent. This vibe-coding approach works for quick prototypes but fails for critical applications or existing codebases. The problem isn't the agent's capability—it's the approach. Developers treat coding agents like search engines, when they should be treated like literal-minded pair programmers who need clear instructions.

To solve this, GitHub open sourced Spec-Kit, a toolkit for Spec-Driven Development (SDD) with AI. With over 90k stars and 8k forks, it's one of the fastest-growing developer tools. This guide walks you through using Spec-Kit to write specifications that guide AI agents to generate code that truly matches your requirements.

What You Need

• Python 3.11 or later installed on your system
• The uv package manager (recommended) or another Python package manager like pip
• An AI coding agent (GitHub Copilot, Claude Code, or similar)
• A GitHub account (optional, but useful for starring/forking the repo)
• Basic familiarity with the command line

Note: Currently, Spec-Kit's CLI is in early development—some features may change quickly. Check the official repository for updates.

Step-by-Step Guide

Step 1: Install the Specify CLI

The core of Spec-Kit is the Specify CLI, a command-line tool that bootstraps projects for SDD. It downloads official templates and helper scripts tailored to your chosen coding agent and platform. Installation is straightforward with uv:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Replace vX.Y.Z with the latest version tag from the releases page. If you prefer pip, use pip install git+https://github.com/github/spec-kit.git. Verify the installation with specify --version.

Step 2: Initialize Your Project

Create a new directory for your project and navigate into it. Then run the initialization command:

specify init <PROJECT_NAME>

Replace <PROJECT_NAME> with your project's desired name (e.g., my-ai-app). The CLI will generate a folder structure containing:

• A spec/ directory for your specification files
• Template files (e.g., spec.md, tech-plan.md)
• Helper scripts for task breakdown and agent integration

This provides a ready-to-use SDD framework.

Step 3: Write a Structured Specification

Open the spec/spec.md file. This is where you describe what you want to build and why, without specifying the tech stack. Follow these guidelines:

• Define the purpose: Explain the problem your project solves.
• List features: Describe each feature in plain language—what it does and why it matters.
• Specify user flows: How will users interact with the system?
• Set acceptance criteria: How will you know when a feature is correct?
• Keep it living: The spec is not a static document—update it as requirements evolve.

A good example: "The app shall allow users to sign up with an email and password, then receive a verification email." Avoid technical details like databases or frameworks—those come later.

Step 4: Feed the Spec into Your AI Coding Agent

Now, use your AI agent (Copilot, Claude Code, etc.) with the specification as the grounding document. In your agent's settings or prompt, include spec/spec.md as a reference. For instance, in Copilot, you can mention: "Based on the specification in spec.md, generate the code for the sign-up feature." The agent will use the spec as the single source of truth, reducing ambiguity.

Spec-Kit's templates also include a technical plan (tech-plan.md) that breaks the spec into tasks an AI agent can execute step by step. Use this to guide the agent's workflow.

Step 5: Generate, Test, and Iterate

Let the AI agent produce code based on the spec. Run the generated code through your tests (including any tests you defined in the spec's acceptance criteria). If something doesn't match, update the spec first—then let the agent regenerate. This flips the traditional flow: spec changes drive code changes, not the other way around.

Repeat this cycle: refine the spec, have the agent generate code, test, and iterate. The spec remains a living artifact that evolves alongside the project.

Step 6: Leverage Templates for Additional Tools

Spec-Kit includes templates for various platforms and agents. Inside specify init, you can choose a template (e.g., for Claude Code or GitHub Copilot). To use a specific template, run:

specify init --template claude <PROJECT_NAME>

This tailors the generated files to that agent's strengths. Check the templates directory for available options.

Tips for Success

• Treat the spec as the contract: Code serves the spec, not the other way around. Update the spec before expecting the agent to change behavior.
• Keep specs concise but clear: Avoid over-specifying every detail—allow the AI room to optimize, but stay unambiguous on requirements.
• Use the tech plan: The tech-plan.md helps break down complex specs into manageable tasks. Use it to guide the agent's step-by-step execution.
• Iterate quickly: The spec is living. Don't try to perfect it upfront; refine as you learn.
• Test early, test often: Include acceptance criteria in your spec and run tests after each generation. This catches intent mismatches fast.
• Remember SDD vs. documentation-first: SDD is not about static documents—it's about a dynamic spec that drives the build process.
• Community contributions: Spec-Kit is open source. If you create useful templates, consider contributing back.

By following these steps, you'll transform how you collaborate with AI coding agents—from vague prompts to precise, spec-driven development that saves time and reduces errors. Start with a small project to learn the workflow, then scale up.