How to Use GitHub Spec-Kit for Spec-Driven Development with AI Coding Agents: A Step-by-Step Guide
Introduction
If you have ever asked an AI coding agent like GitHub Copilot, Claude Code, or Gemini CLI to build something important, you have likely encountered a common frustration: the code looks correct, compiles, yet subtly misses your true intent. This vibe-coding approach works for quick prototypes but falls short for mission-critical applications or existing codebases. The problem, as GitHub points out, is not the agent's skill—it is how we direct them. Developers treat coding agents like search engines when they should treat them as literal-minded pair programmers who need unambiguous instructions.
GitHub's open-source Spec-Kit addresses this by bringing Spec-Driven Development (SDD) to AI coding workflows. With over 90,000 stars and 8,000 forks on GitHub, it has become one of the fastest-growing developer tooling repositories. This guide will walk you through setting up and using Spec-Kit to write specs that guide AI agents accurately, producing higher-quality code with fewer surprises.
What You Need
- GitHub account (to clone or fork the repository)
- Python 3.11 or later (the Specify CLI is Python-based)
- Familiarity with AI coding agents (Copilot, Claude Code, Gemini CLI, or similar)
- Basic command-line skills
- uv package manager (recommended for installing Specify CLI; install uv if needed)
- A project idea or existing codebase to apply Spec-Driven Development
Step-by-Step Guide to Spec-Driven Development with Spec-Kit
Step 1: Install the Specify CLI
Spec-Kit's core tool is the Specify CLI, which bootstraps projects for SDD. Install it using uv (the recommended method) with this command:
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.ZReplace vX.Y.Z with the latest version from the Spec-Kit releases page. Once installed, verify by running specify --help. If you prefer pip, you can also install via pip install specify-cli, but uv ensures isolated environments.
Step 2: Initialize a New Spec-Driven Project
Navigate to your desired directory and run:
specify init <PROJECT_NAME>Replace <PROJECT_NAME> with your project's name (e.g., my-awesome-app). This creates a folder with the official SDD templates, including a structured spec format, a technical plan outline, and helper scripts. The CLI downloads templates tailored to your preferred coding agent and platform.
Step 3: Write a Structured Specification (PRD)
Inside the project folder, you will find a file like spec.md or prd.md. This is your Product Requirements Document – the source that drives all implementation. Write what and why, not how. Use clear, unambiguous language. Example sections:
- Objective: What problem does the feature solve?
- User Stories: Who uses it and how?
- Acceptance Criteria: Bullet points that define done.
- Non-goals: What is explicitly out of scope?
Keep the spec living – you will update it as requirements evolve. Avoid over-specifying technology; let the AI agent choose the best stack based on your constraints.
Step 4: Generate a Technical Plan
Spec-Kit includes scripts that derive a technical plan from your spec. Run the provided helper script (e.g., ./generate-plan.sh or specify plan if available). This produces a document that outlines:
- Architecture decisions
- Component breakdown
- Data flow
- Dependencies
The plan should be a logical decomposition of the spec into concrete technical steps—without code yet. Review it to ensure it matches your intent.
Step 5: Break Down the Plan into AI-Targeted Tasks
From the technical plan, list individual tasks that an AI coding agent can execute sequentially. Each task should be small, self-contained, and reference the relevant section of the spec. For example:
- Task 1: Set up project scaffolding and dependencies
- Task 2: Implement user authentication module per spec section 3
- Task 3: Write unit tests for authentication
Spec-Kit's templates include a tasks/ folder where you can store these as markdown files. This makes it easy to feed them to your AI agent one by one.
Step 6: Use Your AI Agent with the Spec as Grounding
Now feed the spec document and the first task to your AI coding agent. For example, with GitHub Copilot, you can include the spec file in your repository and reference it in the chat. For Claude Code, use claude spec.md tasks/task1.md. The key point: the spec acts as the source of truth. The agent generates code that must satisfy the acceptance criteria. After generating, validate the output against the spec – do not accept code that looks correct but misses intent.
Step 7: Iterate – Update the Spec and Repeat
Spec-Driven Development is not a one-time waterfall. As you get feedback from running the agent or testing the code, update the spec to reflect new requirements or clarifications. Then regenerate the technical plan and tasks, and continue. This keeps the spec alive and ensures the agent always works from the most current instructions.
Tips for Success
To get the most out of Spec-Kit and SDD, keep these points in mind:
- Treat the spec as a contract – both you and the AI agent refer to it when evaluating code quality.
- Avoid too much detail upfront – start with high-level requirements and add granularity only when needed.
- Use acceptance criteria as test cases – have the AI agent generate tests in parallel with implementation.
- Review generated code carefully – the spec reduces ambiguity but does not eliminate it.
- Leverage version control for your spec – treat changes like code changes, with pull requests and reviews.
- Experiment with different agents – Claude Code, Copilot, Gemini – each may interpret specs differently. Adjust your spec style accordingly.
For a quick recap, refer back to Step 1 for installation or Step 3 for writing specs. Happy building!