How to Set Up Spec Kit in Claude Code in 2026: Specifications Instead of Prompts

What happened to vibe coding in May 2026?#

Two things happened in parallel. In September 2025, GitHub published the Spec Kit tool—it gathered 107,000 stars in 8 months. In February 2026, AWS published a detailed drug discovery case study reporting “95% of business logic generated from the specification, saving 80+ hours.”

By the end of May 2026, a consensus had formed in the English-language information space: vibe coding as a working method is the beginner level. Spec-Driven Development comes next. This guide explains how to install and apply the approach.

What are Spec Kit and Spec-Driven Development?#

The methodology’s core idea is captured in one line from GitHub’s official documentation:

In practice, this unfolds in 4 phases (Spec Kit adds one more, a zero phase—constitution, described below):

1. Specify - write a specification of what you want in natural language. WHAT to do and WHY. Not HOW.
2. Plan - the agent takes the specification and assembles a technical plan: which technologies, what architecture, and which components.
3. Tasks - the agent breaks the plan into specific, verifiable tasks with dependencies.
4. Implement - the agent (or its subagents) works through the tasks and writes the code.

After Implement, the current version of Spec Kit has a verification step called Converge: the agent checks the finished code against the specification, plan, and tasks, then adds anything missed to tasks.md. Run Implement and Converge in a loop until Converge responds “Converged.”

Each phase is a separate markdown file in the repo. Each phase is a separate slash command in Claude Code: /speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement, while the check is /speckit-converge. The Spec Kit documentation writes the same commands with a dot (/speckit.specify), but in Claude Code Spec Kit installs them as skills, and they are invoked with a hyphen. If anything goes wrong at any step, edit the markdown file and rerun the next phase.

Spec Kit is a specific implementation of SDD. In May 2026 it already had more than 30 integrations with different AI agents. Within one repo, Spec Kit works the same way with Claude Code, Cursor, GitHub Copilot, Codex CLI, Windsurf, Qwen, Tabnine, Amazon Q, Gemini, Goose, and a dozen more.

So after a run, your repo contains not just code, but also its specification, plan, and tasks. A month later, you can return to the project, read spec.md, and understand what was done and why. This is no longer “vibe coding forgot the code exists”—it is the project’s working memory.

Why does a vibe coder who doesn’t write code need this?#

Spec Kit formalizes planning across separate steps with 4 slash commands. The logic: separate “thinking it through” from “implementing it” so they happen in different context windows. Each stage gets a clean context that hasn’t been cluttered by the previous phase.

Three concrete benefits for a vibe coder:

• Predictability. When you tell the agent “make a registration form with email confirmation,” it guesses 10 details on its own—and gets three of them wrong compared with what you had in mind. When you have a spec.md with User Stories, Acceptance Scenarios, and [NEEDS CLARIFICATION] markers at every uncertain point, there is nothing to guess.
• Project memory. A month later, you won’t remember what you discussed with the agent in chat. But spec.md, plan.md, and tasks.md are in the repo, in the specs/###-feature/ folder alongside the code. They show you not only what was done, but why.
• Scale. For a feature involving 1-2 files, the difference is barely noticeable. For a feature involving 20 files and 5 data entities, the difference is between “rewriting everything after 4 hours” and “everything has made it into the main branch after 4 hours.” AWS Kiro demonstrated 95% automation of business logic from a specification in the TargetID project.

The main illusion of vibe coding is that it looks faster at the start. Half an hour, and there’s a prototype. But by the one-week mark, the prototype breaks, and it is easier to throw it away. Spec-Driven Development takes a little longer at the start (an hour instead of half an hour), but a week later you are still working in the same repo.

How to install Spec Kit in Claude Code (4 steps)#

Step 1. Install uv. You only need to do this once; it stays on your system.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Check that uv was installed:

uv --version

Step 2. Install Spec Kit. One command:

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

Check:

specify --version

Step 3. Initialize the repo. Go to your project folder (or create a new one) and run:

specify init --here --integration claude

The --integration claude flag selects Claude Code directly. Without it, Spec Kit asks you to choose an agent from an interactive list, and may also ask for a script type (for macOS and Linux, leave it as sh). If the folder is not empty, Spec Kit will warn that it will merge its files with yours: commit your work first, then repeat the command with the --force flag.

After that, the following will appear in the repo:

.specify/
  memory/
    constitution.md        # project rules, filled in by /speckit-constitution
  scripts/
  templates/
    spec-template.md
    plan-template.md
    tasks-template.md
.claude/
  skills/
    speckit-constitution/SKILL.md
    speckit-specify/SKILL.md
    speckit-clarify/SKILL.md
    speckit-plan/SKILL.md
    speckit-checklist/SKILL.md
    speckit-tasks/SKILL.md
    speckit-analyze/SKILL.md
    speckit-implement/SKILL.md
    speckit-converge/SKILL.md
    speckit-taskstoissues/SKILL.md

Step 4. Open Claude Code and check the slash commands. Run this in the same folder:

claude

In the session, type /speckit—the speckit-* commands should appear in the suggestions. If they do not, restart Claude Code so it rereads .claude/skills/. If you already have CLAUDE.md at the project root, Spec Kit leaves it alone—it works alongside it, in .specify/memory/constitution.md.

Spec Kit also works without Claude Code (it supports 30+ agents), but this guide covers the setup specifically with Claude. If you want to install two tools right away, see the separate guides on setting up CLAUDE.md and Plan Mode in Claude Code.

How to write your first specification (Specify)#

In Claude Code, type:

/speckit-specify

Then the agent will ask for a description of the feature. At this step, use plain language without technical jargon:

I want a registration form in my app. The user enters an email
and password, receives a confirmation email, and after confirming
lands on the dashboard. Confirmation expires after 48 hours. If the
email is still unconfirmed, delete the account within 5 minutes after
that deadline; never delete a confirmed account.

In this illustrative example, the deletion tolerance has been clarified as 5 minutes after the 48-hour deadline. For a real product, confirm that tolerance before Plan; an exact 48-hour deadline requires a design and tests that enforce that stronger requirement. The agent will assemble specs/001-registration/spec.md. Open it, and you will see a structure like this:

# Feature Specification: User Registration

**Feature Branch**: `001-registration`
**Created**: 2026-05-31
**Status**: Draft
**Input**: User Description: "I want a registration form..."

## User Scenarios & Testing *(mandatory)*

### Primary User Story
As a new user, I want to register an account with email confirmation,
so that I can access the dashboard with a verified identity.

### Acceptance Scenarios
1. **Given** I am on the registration page,
   **When** I submit valid email and password,
   **Then** I receive a confirmation email within 1 minute.
2. **Given** I clicked the confirmation link within 48 hours,
   **When** I land on the dashboard,
   **Then** I see my email confirmed in profile.
3. **Given** I have not confirmed at the 48-hour deadline,
   **When** cleanup runs within the next 5 minutes,
   **Then** my account is deleted and email is freed for re-registration.
4. **Given** my account is just under 48 hours old or already confirmed,
   **When** cleanup runs,
   **Then** the account is not deleted.

## Requirements *(mandatory)*

### Functional Requirements
- **FR-001**: System MUST accept registration via [NEEDS CLARIFICATION:
  email/password only, or also SSO/OAuth?]
- **FR-002**: System MUST send confirmation email within 60 seconds
- **FR-003**: Confirmation MUST expire at 48 hours; the system MUST
  delete still-unconfirmed accounts no later than 5 minutes after that
  deadline and MUST NOT delete confirmed accounts
- **FR-004**: System MUST log all registration attempts for [NEEDS
  CLARIFICATION: how long do we retain logs - 30 days, 90 days, forever?]

### Key Entities
- User: email, password_hash, email_verified_at, created_at, deleted_at
- ConfirmationToken: token, user_id, expires_at, used_at

## Success Criteria *(mandatory)*
- **SC-001**: 95% of confirmation emails delivered within 60 seconds (p95)
- **SC-002**: 0 accidental deletions of confirmed accounts
- **SC-004**: No deletion before 48 hours; every eligible unconfirmed
  account is deleted by age 48 hours 5 minutes under the tested workload
- **SC-003**: Registration completion rate > 60% (from form open to dashboard)

Pay attention to the [NEEDS CLARIFICATION: ...] markers. Spec Kit deliberately inserts them wherever the agent did not get an unambiguous answer from your text. Before moving to the Plan phase, you must either answer them manually in spec.md or run /speckit-clarify, and the agent will go through the unclear points and ask questions in the dialogue.

In Spec Kit, the built-in /speckit-clarify command asks you the clarifying questions: you do not move on to Plan until there are no [NEEDS CLARIFICATION] markers left in spec.md.

There should be no technologies in spec.md. No mentions of React, Postgres, Prisma, or Redis. The specification describes what the system does from the user’s and business’s perspective. The technology stack comes in the next phase.

What does Claude do in the Plan phase?#

When spec.md is ready, run:

/speckit-plan

Optionally, pass technology hints directly in the command:

/speckit-plan Next.js App Router, Prisma, PostgreSQL, Resend for email

Claude reads three sources: your spec.md, your CLAUDE.md (or memory/constitution.md), and the existing code in the repo. The output is a plan.md with a structure roughly like this:

# Implementation Plan: User Registration

## Technical Context
- Framework: Next.js 14 App Router
- Database: PostgreSQL via Prisma
- Email: Resend (single transport)
- Validation: Zod schema in shared lib
- Auth: NextAuth.js with credentials provider

## Architecture Decisions

### 1. Token storage
Tokens stored in DB (table ConfirmationToken), not in JWT.
Reason: need server-side revoke on email re-register.

### 2. Email delivery
Async via cron `/api/cron/send-confirmation` triggered immediately
after registration. Retries handled by Resend.

### 3. Auto-delete cron
Run `/api/cron/cleanup-unconfirmed` every minute. Delete rows only where
created_at <= NOW() - INTERVAL '48 hours' AND email_verified_at IS NULL.
The clarified example allows at most 5 minutes of deletion delay.
Verify scheduler lag and completion time against that bound; report
a missed bound as a failure, not a successful daily cleanup.

## Data Model
See data-model.md

## API Contracts
See contracts/
- POST /api/auth/register
- POST /api/auth/confirm
- GET /api/auth/resend-confirmation

## Implementation Phases
1. Database migration (Prisma schema + migration file)
2. API routes (3 endpoints)
3. UI: registration form + confirmation success page
4. Cron jobs (send + cleanup)
5. Email template
6. Integration tests

data-model.md will describe the entities and their relationships. contracts/ will contain API contract stubs (either OpenAPI YAML or TypeScript request/response types). This is not code—it is intent that Claude will later turn into actual routes.

The main advantage of the Plan phase is clean context. Claude does not try to keep both the specification and implementation in mind at the same time. It thinks things through first, records the decision in a file, and then moves on.

Next, there is the optional /speckit-analyze command. It is run after the Tasks phase and before Implement: it reviews the spec.md + plan.md + tasks.md set for contradictions and checks whether all specification requirements are covered by the plan and tasks. It does not edit files; it only produces a report. Essentially, it is a formal sanity check before implementation.

How to break work into tasks (Tasks)#

Once you have spec.md and plan.md, run:

/speckit-tasks

Claude expands the plan into tasks.md:

# Tasks: User Registration

## Phase 1: Database (no dependencies)
- [ ] T-001: Add User model to prisma/schema.prisma (parallel-safe)
- [ ] T-002: Add ConfirmationToken model to prisma/schema.prisma (after T-001)
- [ ] T-003: Generate migration `add-user-registration` (after T-002)

## Phase 2: API contracts (no dependencies)
- [ ] T-004: Create Zod schemas in shared/validation/auth.ts
- [ ] T-005: Define TypeScript types in shared/types/auth.ts (after T-004)

## Phase 3: Routes (depends on Phase 1+2)
- [ ] T-006: Implement POST /api/auth/register
- [ ] T-007: Implement POST /api/auth/confirm
- [ ] T-008: Implement GET /api/auth/resend-confirmation

## Phase 4: UI (parallel with Phase 3)
- [ ] T-009: Build /register page with form
- [ ] T-010: Build /register/confirm/[token] page
- [ ] T-011: Build /register/success page

## Phase 5: Cron + integration (depends on Phase 3+4)
- [ ] T-012: Cron /api/cron/send-confirmation
- [ ] T-013: Cron /api/cron/cleanup-unconfirmed
- [ ] T-014: Email template registration-confirmation.tsx
- [ ] T-015: Integration tests (Playwright), including cleanup just
  before 48h, exactly at 48h, deletion by 48h 5m, delayed-job failure,
  and protection of confirmed accounts

## Notes
- T-001, T-004, T-009-T-011 are parallel-safe (different files)
- T-002 conflicts with T-001 (same file: schema.prisma) - run sequentially
- T-006 needs T-003 (migration applied) and T-005 (types)

Note the parallel-safe and after T-NNN markers. This is the dependency graph that later lets you run several phases in parallel. The entire Spec Kit acceleration approach rests on this mechanism: some tasks can be handed to five different Claude Code sessions at once, while others must be strictly sequential.

Spec Kit does this automatically with one command, right out of the box.

The optional /speckit-taskstoissues command takes tasks.md and creates GitHub Issues from the list, each with a link back to spec.md. This is useful if you work on a team or want to track progress through GitHub Projects.

How to implement with subagents (Implement)#

/speckit-implement

Claude starts with the first task in tasks.md. Each task goes through a small cycle: read the relevant files, write a diff, run the tests, check [x]. Subagents are called automatically where needed: a separate one for code review, a separate one to run the linter, and a separate one to check for regressions.

In Spec Kit, this cycle is formalized. You have spec.md as the source of truth, plan.md for technical decisions, and tasks.md as a checklist. If Claude goes off track at any step, you return to the specification and say, “That doesn’t match FR-003; redo it.” No long prompts saying “remember what we discussed...” — the entire history is in the files.

If you have connected Dynamic Workflows in Opus 4.8, you can put Spec Kit into full automation mode: one /speckit-implement command and Claude parallelizes the work, consolidates results, and checks them. The limit is 1000 subagents at once. For most features, 10-30 are enough.

When all [x] boxes are checked and the check in the next section returns “Converged,” you review the PR (or a series of PRs if there are many tasks) and merge it. The artifacts—spec.md, plan.md, tasks.md—remain in the repo as the feature’s documentation. A year later, you will not have to reverse engineer the logic from the code.

How to check that the agent has not missed anything (Converge)#

/speckit-converge

First the agent gives a summary of what it found, with severity levels, then one of two outcomes. “Converged” means there are no omissions, tasks.md remains byte-for-byte unchanged, and you can move on to review. “Tasks appended” means omissions were found, they were added to the Convergence section in tasks.md, and the agent tells you how many there are.

Converge does not edit or delete code; its only write is new tasks in tasks.md. So you can run it without concern, but only after /speckit-implement has already worked through the current tasks.md. Each subsequent pass finds fewer omissions.

How does Spec Kit differ from CLAUDE.md and Plan Mode?#

Compare them across 5 characteristics:

In Spec Kit terms, the counterpart of CLAUDE.md is .specify/memory/constitution.md. During initialization, Spec Kit can either use your existing CLAUDE.md as the basis for the constitution or create a separate file alongside it. I usually keep CLAUDE.md as the global “contract” (stack, glossary, deployment protocol), and use the Spec Kit constitution for feature-specific rules—for example, “all forms are validated through Zod; no manual checks.”

The connection with Plan Mode is simpler. Plan Mode is a quick “plan before writing code” mode within a single session. It works well for small changes (fix a bug, refactor a function). For a large feature, Plan Mode loses out because one session’s context window is too small for a 3000-line plan.

Spec Kit is a concrete context engineering tool. It moves the architecture description from chat into files. Spec.md stays in the repo, and every new Claude session reads it again—you do not have to repeat yourself.

A setup for a large project:

1. CLAUDE.md - stack, glossary, what not to do. It lives in the root.
2. .specify/memory/constitution.md for Spec Kit—rules specific to this workflow.
3. specs/001-feature-A/spec.md, plan.md, tasks.md - first feature.
4. specs/002-feature-B/spec.md, plan.md, tasks.md - second feature.
5. For daily work, either /speckit-implement (for ready-made tasks) or /plan (a quick double-check before a change).

Which real-world cases are working?#

Specific cases:

• AWS Kiro - drug discovery agent. In an AWS Industries blog post dated February 18, 2026, the team describes the TargetID project. Three developers, three weeks, a drug discovery agent. The figures in the article: Kiro generated more than 95% of the business logic code, saving more than 80 development hours. Also: “README documentation written by Kiro saved us an estimated 8 hours” and “40% fewer iterative prompt-and-fix cycles.”
• Rackspace Technology. In the same AWS blog, Rackspace reports: “completed 52 weeks of estimated work in just 3 weeks,” “90% increase in efficiency.” This is no longer a small feature—it is a full enterprise project.
• GitHub Spec Kit growth. As of May 7, 2026, the repo had 93,000 stars; by May 31, it had 107,000. That is +14,000 stars in three weeks. This growth rate is a clear signal that the approach is gaining market share.

For the reader, this means the approach is not theoretical: serious teams are already using it in production.

When is Spec Kit NOT suitable?#

Not suitable #1 - small edits. If the task is “rename a variable,” “fix a typo in the copy,” or “add a log,” running through Specify → Plan → Tasks will take longer than the edit itself. For small edits, Plan Mode or simply a direct prompt in Claude Code is faster.

Not suitable #2 - live experiments. When you do not yet know what you want and need to “poke around” in the interface or quickly assemble a prototype to see “if it lands,” a specification is pointless. The value lies in the very fact that you are improvising. At the level of “playing with an idea,” vibe is exactly what works, not a specification.

Not suitable #3 - legacy code with complex state. A strong counterargument: reality changes faster than specifications. Take subscription billing: the team described billing cycles and tax rules, then a week later Finance asked for European VAT—the spec was outdated before release. When business logic evolves quickly, maintaining specs becomes a burden.

An additional risk is a false sense of control: structures are elegant, but agents often ignore instructions or, conversely, follow templates too literally. The result is code that is structurally correct but does not fit your specific repo—the spec does not guarantee that the agent understood it as you intended.

Industry analysts have warned about waterfall: writing a large specification before code is a path that has already sunk the industry once, back in the days of 200-page requirements. Engineers have been cautious about this approach ever since, and that caution is justified.

What to do about it. I suggest a simple rule: feature size versus time to write a specification. If a feature will take less than 2 hours to implement, do not write a spec—Plan Mode is faster. If a feature will take a week, definitely use Spec Kit; the time savings will repay the hour-long specification fivefold. Between 2 hours and a week, use your judgment, though I personally write a spec even for half-day features because the artifact in the repo is worth more than the 30 minutes saved.

What next: how to integrate Spec Kit into your project?#

A concrete plan for the next 7 days:

• Day 1. Install uv and Spec Kit (5-10 minutes). Check that the /speckit-* commands have appeared in your Claude Code. Do not try to apply them to an existing project—start with a new one.
• Day 2. Pick a real feature you plan to build. Run /speckit-specify with a free-form description. Open spec.md, read it, and answer every [NEEDS CLARIFICATION]. Do not rush into Plan.
• Day 3. Run /speckit-plan with hints about your stack. Read plan.md, especially the Architecture Decisions section. If something does not suit you, edit it manually.
• Day 4-5. Run /speckit-tasks, then /speckit-analyze to double-check the spec, plan, and tasks set, then /speckit-implement. Watch how Claude checks off [x] in tasks.md. It may get stuck somewhere—that is normal. Return to spec.md, clarify the requirement, and restart /speckit-implement with a specific task. Once the tasks are closed, run /speckit-converge and repeat the Implement and Converge sequence until it responds “Converged.”
• Day 6-7. Review the PR (or series of PRs). Merge it. Read your spec.md and plan.md—they are your feature documentation for the coming year.

What I would suggest reading in parallel:

• How to set up CLAUDE.md in 2026 - the basis for Spec Kit’s constitution.
• Plan Mode in Claude Code - a quick alternative for small tasks.
• Context engineering in 2026 - why Spec Kit works at all.
• Skills, Subagents, MCP, or Plugins - what to add to Spec Kit for your workflow.
• Dynamic Workflows in Claude Code - how to launch many subagents at once for the Implement phase.

More materials are available on Ailoot.