HomeGuidesSpec Kit How To Use Specifications To Generate Code With Ai

Spec-Kit: How to Use Specifications to Generate Code with AI

Published Nov 26, 2025
⋅
Updated Nov 28, 2025
⋅
5 minutes read

You prompt an AI assistant. It generates code. You test it. Something breaks. You prompt again. More code. More bugs. Three hours later, you're debugging a tangled mess that barely resembles what you originally wanted.

Sound familiar?

The Hidden Cost of "Vibe Coding"

Here's what the data shows: a study from Uplevel found that using GitHub Copilot introduced 41% more bugs into codebases. Apiiro's 2024 research revealed AI-generated code introduced 322% more privilege escalation paths and 153% more design flaws compared to human-written code.

Perhaps most concerning: a Stanford study published at ACM CCS '23 found that developers with access to AI assistants wrote significantly less secure code — while simultaneously being more confident in its security. The dangerous combination of worse output and inflated confidence.

The worst part? Developers consistently overestimate AI's impact on their productivity by nearly 40 percentage points. We feel more productive while actually shipping worse software.

This is the "70% problem": AI gets you 70% of the way there surprisingly fast, but that final 30% — the part that makes software production-ready, maintainable, and robust — becomes an exercise in diminishing returns.

Each new iteration of AI-generated code ends up less consistent. Different parts of your codebase developed with different prompts start conflicting. Debugging becomes so resource-intensive that it's often easier to rewrite everything from scratch than to fix it.

Why This Keeps Happening

The root cause isn't the AI — it's how we're using it.

When you jump straight into prompting without clear specifications, you're essentially asking an AI to read your mind. It can't. So it guesses. And each guess compounds into more guesses, creating a cascade of assumptions that diverge further from your actual intent.

Traditional development recognized this problem decades ago. That's why we have PRDs, technical specs, and design documents. But these artifacts became bureaucratic overhead — created once, then ignored as code took on a life of its own.

What if there was a way to make specifications actually matter? To make them so precise that AI could reliably translate them into working code?

Enter Spec-Driven Development

Spec-Kit is an open-source toolkit from GitHub that implements Spec-Driven Development (SDD) — an approach that inverts the traditional power structure between specifications and code.

In conventional development, code is king. Specifications merely guide it. In SDD, specifications are supreme, and code serves them.

The transformation is fundamental: PRDs and technical plans don't just guide implementation — they generate it. What might take days of meetings becomes hours of focused specification work. And because the specs are precise enough for AI to execute, they remain the single source of truth.

This isn't about slowing down to write more documentation. It's about front-loading the thinking so the AI can handle the mechanical translation accurately.

How Spec-Kit Works

Spec-Kit structures development into six phases, each with a dedicated slash command that works with your AI coding assistant:

Phase 1: Constitution

Before writing any code, establish your project's governing principles with /speckit.constitution.

This creates your "Phase -1 Gate" — architectural decisions that must be respected throughout development:

Think of it as programming the AI's judgment before it writes a single line.

Phase 2: Specify

Use /speckit.specify to describe what you want to build and why — without mentioning technology:

"Build an application that helps me organize photos into separate albums. Users should be able to create albums, add photos, and share albums with friends."

This forces you to think about user needs, not implementation details. The AI won't prematurely optimize for a specific framework or pattern.

Phase 3: Clarify

Run /speckit.clarify to eliminate ambiguity. The AI asks probing questions about edge cases, user flows, and requirements you might have missed.

This is where most "vibe coding" projects fail. Without explicit clarification, AI fills gaps with assumptions. With Spec-Kit, every assumption becomes an explicit decision you make.

Phase 4: Plan

Now define your technical approach with /speckit.plan:

"Use Vite with vanilla HTML, CSS, and JavaScript. Minimize dependencies. Store data in IndexedDB for offline support."

Every technical choice gets documented rationale. When you revisit the project in six months, you'll know why you made each decision — not just what you decided.

Phase 5: Tasks

/speckit.tasks generates an actionable task list organized by user stories, with:

This is your executable roadmap.

Phase 6: Implement

Finally, /speckit.implement executes all tasks automatically, following the order and constraints you've defined.

The AI isn't guessing anymore. It's translating precise specifications into code — the mechanical work it actually excels at.

Real-World Impact

Consider building a real-time chat system with message history and presence indicators.

Traditional AI-assisted approach:

  1. Prompt for basic chat functionality (30 min)
  2. Debug WebSocket issues (1 hour)
  3. Realize message history wasn't specified (30 min)
  4. Prompt for database integration (1 hour)
  5. Fix conflicts between chat and history code (2 hours)
  6. Add presence indicators (1 hour)
  7. Refactor because components don't fit together (3 hours)
  8. Write tests for the mess (2 hours)

Total: ~11 hours of fragmented work with inconsistent code quality.

Spec-Kit approach:

/speckit.specify Real-time chat with history and presence
/speckit.clarify
/speckit.plan WebSocket, PostgreSQL, Redis
/speckit.tasks
/speckit.implement

Total: ~45 minutes including specification time, with:

The difference isn't just speed — it's coherence. Every component knows about every other component from the start.

The Nine Constitutional Articles

Spec-Kit's default constitution enforces battle-tested engineering principles:

ArticlePrincipleWhy It Matters
ILibrary-FirstEvery feature starts as a standalone library — forcing clean interfaces
IICLI MandateAll libraries expose CLI functionality — enabling automation and testing
IIITest-FirstNo code before failing tests exist — ensuring testability from day one
IV-VIDocumentationComprehensive docs and examples — knowledge transfer built-in
VIISimplicityMaximum 3 projects initially — preventing premature complexity
VIIIAnti-AbstractionUse framework features directly — avoiding abstraction layers that obscure behavior
IXIntegration-FirstReal environments, not mocks — catching integration issues early

You can customize these for your project's specific needs, but the defaults represent hard-won wisdom from production systems.

Getting Started

Prerequisites

Installation

Persistent install (recommended):

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify init my-project
specify check

One-time usage:

uvx --from git+https://github.com/github/spec-kit.git specify init my-project

Supported AI Assistants

Spec-Kit works with most major tools:

When to Use Spec-Driven Development

SDD excels for:

Skip SDD for:

The Fundamental Shift

Spec-Driven Development isn't about replacing developers or automating creativity. It's about amplifying human capability by automating the mechanical translation from intent to implementation.

AI coding assistants are like having a very eager junior developer on your team. They write code quickly but need constant supervision. The more clearly you specify what you want, the better they perform.

Spec-Kit gives you a structured way to be clear. Instead of hoping the AI understands your vague prompt, you systematically eliminate ambiguity before generation begins.

The result: code that actually matches what you intended, produced faster than traditional development, with fewer bugs than unstructured AI assistance.

Ready to stop vibe coding and start building software that matches your intentions? Check out the Spec-Kit repository and read the full Spec-Driven Development methodology.