Spec-Driven Development with AI: The 2026 Guide to GitHub Spec Kit

You prompted the agent. It wrote 400 lines. Half of them solved the wrong problem. Welcome to vibe coding at scale — the thing every team learned to regret in 2025.

Spec-driven development (SDD) is the fix that stuck. Instead of chatting at your AI agent and praying, you write a spec, the agent turns it into a plan, the plan becomes tasks, and tasks become code you actually trust. GitHub's Spec Kit made this workflow open source in late 2025 and it's now the fastest-growing approach to AI coding in 2026.

This guide walks both sides of the room: the what and why for anyone managing AI-built software, and the how — commands, files, and prompts — for engineers ready to ship with it today.

📋 What You'll Need

• An AI coding agent: Claude Code, GitHub Copilot (agent mode), Gemini CLI, or Cursor
• Python 3.11+ with the uv package manager installed
• A Git repository (greenfield or existing — both work)
• Ten minutes to understand the four-phase loop before you run a single command
• A willingness to write specs instead of prompts — this is the whole game

No paid license is required. Spec Kit is open source and free.

🧭 What Spec-Driven Development Actually Is

Spec-driven development flips the traditional order of operations. Code is no longer the source of truth — the specification is. The code is a generated artifact, and the AI agent is the thing that generates it.

That sounds academic until you see the failure mode it cures. In vibe coding, the "truth" about your system lives in a chat history that resets every time the context window fills up. The agent forgets. You forget. New features contradict old ones. SDD makes the truth a file on disk.

The four-phase loop

Every spec-driven workflow — whether you use Spec Kit, Kiro, BMAD, or homegrown templates — runs the same sequence:

1. Specify — You describe what to build and why, in user terms. No tech stack.
2. Plan — You add the how: architecture, libraries, data model, constraints.
3. Tasks — The agent breaks the plan into small, reviewable work units.
4. Implement — The agent executes tasks one at a time, in order, against the spec.

Each phase produces a markdown file the next phase reads. Nothing is in the agent's head alone.

🆚 Spec-Driven vs Vibe Coding

Both approaches exist on the same spectrum, and neither is universally right. Pick based on the stakes.

The honest take: start vibe, finish spec-driven. Explore an idea in a freewheeling chat. When the shape is clear, write the spec and hand it back to the agent. See Vibe Coding Explained for the other half of this story.

⚙️ Installing GitHub Spec Kit

Spec Kit ships as a Python CLI called Specify. Install it with uv:

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the Specify CLI
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Then initialize a project:

# New project
specify init my-photo-app --ai claude

# Or bolt it onto an existing repo
cd my-existing-project
specify init . --ai copilot

The --ai flag tells Spec Kit which agent you're wiring it into. Supported values in April 2026 include claude, copilot, gemini, and cursor. Each target writes slash commands into the agent's config directory so you can call /speckit.specify, /speckit.plan, etc. from inside your coding session.

What Spec Kit drops into your repo

my-photo-app/
├── .specify/
│   ├── memory/
│   │   └── constitution.md    # Project principles
│   ├── specs/
│   │   └── 001-albums/
│   │       ├── spec.md        # What to build
│   │       ├── plan.md        # How to build it
│   │       └── tasks.md       # Work breakdown
│   └── templates/             # Slash command scaffolds
└── ...your code...

Every feature lives in its own numbered folder under specs/. Specs, plans, and tasks are all plain markdown — commit them with your code.

🛠️ The Seven Spec Kit Commands

Once Spec Kit is installed, your agent exposes seven slash commands. You'll use four of them constantly and three occasionally.

You don't have to run all seven. A minimal flow is specify → plan → tasks → implement. Add constitution once per project and clarify/analyze when you're unsure.

🎯 A Full Walkthrough: Building a Photo Album App

Let's run the loop end to end. The example is deliberately small so you can see every file it produces.

Step 1 — Write the constitution

In your agent session, run:

/speckit.constitution

Principles:
- TypeScript only, strict mode
- No external state management libraries
- Every feature must have integration tests
- Accessibility: WCAG 2.1 AA minimum
- No telemetry without explicit user opt-in

This writes .specify/memory/constitution.md. Every future spec, plan, and task will be checked against it.

Step 2 — Specify the feature

/speckit.specify

Build an app to organize photos into albums. Users can drag
photos between albums on the main page. Each album shows a
tiled preview of its contents, grouped by the date the
photos were taken. Photos can belong to multiple albums.

Notice what's missing: no framework, no database, no API design. That's intentional. The spec captures user value, not implementation. The agent writes spec.md with user stories, acceptance criteria, and open questions.

Step 3 — Clarify ambiguities

/speckit.clarify

The agent re-reads spec.md and asks pointed questions: "What happens when a photo is deleted from one album but still exists in another?" Answer inline. The spec gets updated. This step alone kills more bugs than any test suite you'll ever write.

Step 4 — Plan the implementation

/speckit.plan

Use Vite + React + TypeScript. Store metadata in SQLite via
better-sqlite3. Image files live on the local filesystem.
Drag-and-drop via dnd-kit. No backend — this is a desktop
app built with Tauri.

Now the agent writes plan.md: data model, file structure, component tree, and which parts of the spec each piece satisfies.

Step 5 — Generate tasks

/speckit.tasks

The agent produces tasks.md — usually 15 to 40 small tasks, each with a title, scope, and "done when" criteria. Review it like a pull request. Delete, reorder, or rewrite tasks before moving on.

Step 6 — Implement

/speckit.implement

The agent works through tasks.md top to bottom, one task per turn, updating the file as it goes. You review each change. If something drifts, you stop, edit the spec, and re-run /speckit.plan or /speckit.tasks for just the affected slice.

🧩 Where SDD Fits in Your Workflow

Spec-driven development is a tool, not a religion. Three places it pays off immediately:

Greenfield features

You're starting from zero. There's no codebase to guess at, no legacy to protect. The spec is the cheapest place to be wrong, because wrong specs cost keystrokes — wrong code costs refactors.

Cross-team handoffs

A PM writes the spec. An engineer writes the plan. An AI agent writes the tasks. A second engineer reviews the implementation. Every step has a durable artifact and an owner. The spec becomes the contract between roles.

Legacy modernization

You're rewriting a 10-year-old module that nobody fully understands. Use /speckit.specify to reverse-engineer the current behavior into a spec first. Then write a new plan against the same spec. The spec preserves what the module does while you rebuild how it does it.

Where it doesn't fit: five-line bug fixes, ad-hoc data pulls, weekend hacks. Writing a spec for those is the engineering equivalent of filing a JIRA ticket to brush your teeth.

📊 Spec Kit vs the Other SDD Tools

Spec Kit isn't the only player. In 2026 the three serious options are:

Spec Kit wins on neutrality. It works with Claude Code, Copilot, Gemini, and Cursor without forcing you to pick one. That matters in a year where "which agent is best" changes every quarter. For more on picking agents, see AI Coding Agents Compared 2026.

🧪 Spec-Driven Development and Tests

SDD and test-driven development are natural partners, not competitors. The spec says what. Tests prove it works. The code is the thing that makes both true.

A simple rhythm that works:

1. /speckit.specify writes spec.md
2. /speckit.plan adds a test strategy section to plan.md
3. /speckit.tasks generates a test task before each implementation task
4. /speckit.implement writes the test first, then the code, then verifies

This is red-green-refactor with the agent doing the typing. The spec is what keeps the agent from writing tests that "pass but don't prove anything" — the single most common failure mode of AI-generated TDD. If you want the deep dive, see Test-Driven Development with AI Agents.

🐛 Troubleshooting

Common snags when you first adopt Spec Kit:

💰 Cost Breakdown

Spec Kit itself is free. The cost lives entirely in the agent you pair it with.

Spec-driven workflows consume more tokens per feature than vibe coding because the agent reads spec, plan, and tasks on every turn. Budget roughly 20-40% higher API spend, offset by fewer wasted implementation cycles.

🚀 What's Next

• 📝 Write your first constitution. Spend 20 minutes on this before any spec. It pays back 10x.
• 🧱 Try it on a throwaway feature first. Pick a small CRUD screen. Run the full loop. Feel the rhythm.
• 🔄 Learn the Claude Code Workflow Guide — it pairs naturally with Spec Kit.
• 🛡️ Read up on AI Coding Agents Security Risks before letting an agent implement unattended.
• 📖 Bookmark the official Spec Kit repo — it ships updates weekly.

Ready to go deeper? Read the Claude Code Workflow Guide for the agent side of the loop, or see AI Coding Agents Compared 2026 to pick the right engine for your specs.