Skip to main content
Intermediate

Spec-Driven Development with Spec Kit

Vibe coding — "build me a dashboard," accept whatever comes back — works great until the feature gets big. Then the agent drifts: it forgets an earlier decision, re-invents a function, or ships something that technically runs but isn't what you meant. Spec-Driven Development (SDD) is the fix that's caught on across the agentic-coding crowd in 2026: instead of treating the prompt as throwaway, you make a written, reviewable specification the source of truth and have the agent generate code from it.

GitHub's open-source Spec Kit turns that idea into a concrete workflow you can run inside Claude Code today.

What you'll learn
  • Understand what spec-driven development is and the problem it solves
  • Walk the Spec Kit phases: constitution → specify → plan → tasks → implement
  • Install the Specify CLI and wire it into Claude Code
  • Know the optional quality gates (clarify, analyze, checklist)
  • Decide when SDD is worth the overhead and when to skip it

Why specs, not just prompts​

A prompt is gone the moment the turn ends. A spec is an artifact: it can be read, reviewed in a PR, corrected, and re-run. That single shift fixes the three ways big agentic builds go wrong:

  • Drift — the agent contradicts an earlier decision because nothing wrote it down. The spec is the memory.
  • Ambiguity — "make it nice" means ten different things. Forcing requirements into prose surfaces the gaps before code exists, where they're cheap to fix.
  • Unreviewable diffs — a 2,000-line generated PR is hard to judge. A reviewed spec + plan makes the diff expected instead of surprising.

The mental model: intent is the high-value, durable thing; code is a downstream, regenerable artifact. SDD is the disciplined cousin of Claude Code's own Plan Mode — plan first, build second — scaled up to a whole feature and persisted to files in your repo.

The Spec Kit workflow​

Spec Kit structures a feature as a short pipeline of slash commands. Each one writes Markdown artifacts into your repo (under .specify/), so every phase is inspectable and version-controlled.

Guided walkthrough1 of 5
  1. Run /speckit.constitution once per project. It writes governing principles — code style, testing bar, architectural non-negotiables — into .specify/memory/constitution.md. Every later phase is checked against it, so this is your durable guardrail (think of it as a CLAUDE.md focused on principles).

Optional quality gates​

Three more commands tighten the loop when a feature is high-stakes:

  • /speckit.clarify — interrogates the spec for under-specified areas and asks you targeted questions before planning. Best run right after specify.
  • /speckit.analyze — cross-checks the spec, plan, and tasks for consistency and coverage gaps.
  • /speckit.checklist — generates a validation checklist so "done" is defined and testable.
Pro tip
  • Run /speckit.clarify before /speckit.plan — fixing ambiguity is cheapest before architecture is committed.
  • Treat each generated artifact like a PR: read it, correct it, and only then advance to the next phase.
  • Commit the .specify/ artifacts — they're the reviewable record of intent behind the code.

Get it running with Claude Code​

Spec Kit ships a CLI, Specify, that scaffolds the slash commands into your project. It supports 30+ coding agents, Claude Code among them.

Guided walkthrough1 of 3
  1. Use uv to install it from the repo. (Python + uv required.)

Install the Specify CLI (uv)

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

Scaffold spec-driven workflow into a project

# new project
specify init my-feature

# or in the current repo
specify init --here

Then, inside Claude Code, run the pipeline

/speckit.constitution Establish principles: TypeScript strict, tests for every public function, no secrets in code.
/speckit.specify Build a CSV export for the reports page: users pick a date range and download a CSV of matching rows.
/speckit.clarify
/speckit.plan Next.js App Router, server action for the query, stream the CSV; no new dependencies.
/speckit.tasks
/speckit.implement
Watch out
  • The exact agent-selection flag for specify init changes between releases — check the README quickstart rather than copying a flag blindly.
  • SDD does not remove the need to verify: read the generated code and run it. The spec makes the diff reviewable, not automatically correct.
  • Never put secrets or credentials in the spec, plan, or constitution — they get committed like any other file.

When to use it (and when not)​

SDD trades upfront ceremony for control. That trade is worth it when the work is big, ambiguous, or must be reviewed by others — and pure overhead when it isn't.

What you'll learn
  • Reach for SDD: greenfield features, multi-file builds, anything a teammate must review, or work you'll hand to a subagent fleet.
  • Skip SDD: one-off scripts, tiny fixes, exploratory throwaway code — a plain prompt or Plan Mode is faster.
  • Brownfield works too: point /speckit.specify at an enhancement to an existing codebase, not just new projects.
SDD at a glance
Press Enter or Space to flip the card. Use the left and right arrow keys to move between cards.Term shown.
1 / 5

Check yourself​

Check yourself

0/3
  1. What is the core idea of spec-driven development?
  2. Which Spec Kit phase should capture the technology stack and architecture?
  3. When is spec-driven development NOT worth the overhead?
Key takeaways
  • Spec-driven development makes a reviewable spec — not the prompt — the source of truth, killing drift, ambiguity, and unreviewable diffs.
  • GitHub's Spec Kit (the Specify CLI) brings SDD into Claude Code as /speckit.* slash commands.
  • The pipeline is constitution → specify → (clarify) → plan → (analyze) → tasks → (checklist) → implement, each writing inspectable artifacts.
  • Keep WHAT/WHY in the spec and HOW in the plan; review every artifact like a PR before advancing.
  • Use it for big, ambiguous, or reviewed features; skip it for throwaway work — and always still verify the generated code.

Next​

Sources & further reading​