lockstep
4 min readNaman Jain

Spec Kit with Claude Code: setup and workflow

GitHub Spec Kit with Claude Code: install, specify init --integration claude, the constitution-to-converge workflow, and keeping skills out of context.

A team tries spec-driven development with Claude Code. The first feature goes well: a clear spec, a plan, tasks, working code. By the fifth, Claude starts running Spec Kit steps nobody asked for, because every Spec Kit skill's description is sitting in its context and matching ordinary requests.

This guide covers setting up GitHub's Spec Kit with Claude Code, the workflow, and that context setting, from the Spec Kit README and its Claude Code integration page, checked on 16 November 2026.

What Spec Kit is

Spec Kit is GitHub's open-source toolkit that gives coding agents structured processes, templates, and recorded outcomes. Its core process is spec-driven development: define what to build and why, then turn that spec into a plan, tasks, and code. It also ships bug-fixing and idea-assessment processes as extensions.

It supports dozens of agents through integrations. Claude Code's key is claude.

Setup

You need Python 3.11 or later, uv, and Claude Code installed.

uv tool install specify-cli
specify init my-project --integration claude
cd my-project
claude

For an existing Spec Kit project, add Claude Code with specify integration install claude. For a codebase that doesn't use Spec Kit yet, follow its existing projects guide.

Spec Kit installs each step as a Claude Code skill at .claude/skills/speckit-<command>/SKILL.md.

Keep the skills out of Claude's context

By default, every Spec Kit skill for Claude Code is model-invocable: its description is always in Claude's context and counts toward the skill-listing budget. In a project with many skills, Spec Kit's docs note this can push other skills out of the listing.

To make the core skills run only when you type them:

specify init my-project --integration claude \
  --integration-options="--no-model-invocation"

This writes disable-model-invocation: true into the core command skills. Extension skills stay model-invocable, because their mandatory hooks depend on Claude invoking them. Spec Kit's docs warn not to use the option if an extension's mandatory hook runs a core command.

The workflow

Run these in Claude Code's chat, one at a time, reviewing each result before the next:

/speckit-constitution Principles: code quality, tests for every endpoint, no new dependencies without review.
/speckit-specify Let admins export the member list as CSV, filtered by role and last active date.
/speckit-plan Use the existing export service and background jobs. No new tables.
/speckit-tasks
/speckit-implement
/speckit-converge
StepWhat it produces
/speckit-constitutionProject principles every later step follows; once per project
/speckit-specifyThe spec: what and why, from the user's side
/speckit-planThe technical plan: how, with your stack choices
/speckit-tasksAn ordered task list from the plan
/speckit-implementCode for the tasks
/speckit-convergeA check of the result against the spec; repeat implement and converge until it reports Converged

The README points to further steps for clarification, checklists, and consistency analysis in the SDD walkthrough.

Tips for Claude Code

  • Keep the spec free of the how. Put stack choices in /speckit-plan, not /speckit-specify. See the PRD template for AI coding agents for writing requirements an agent reads literally.
  • Plan mode pairs well with the plan step: you review before anything is edited. See plan mode vs auto mode.
  • Commit the spec and plan. They're the record of why the code looks the way it does, and the next session reads them.
  • Use the constitution for stable rules, not for decisions that change every sprint.

Where specs go stale

A spec is accurate the day it's written. Then the team changes a decision in a review thread, and the spec, the plan, and the next /speckit-implement run don't know. The problems with spec-driven development mostly come from that gap.

Where Lockstep fits

Lockstep keeps the decisions that change after the spec is written. It captures them from PRDs, Slack, and pull requests, routes each to its owner for approval, and briefs Claude Code sessions, including ones running Spec Kit steps, on the approved decisions that apply to the work.

See how it works.

Sources checked 16 November 2026

For Spec Kit against other spec tools, see Spec Kit vs Kiro vs OpenSpec vs BMAD. For the PM side, see spec-driven development for product managers. For a spec-first agent with this built in, see Kiro vs Claude Code.

Frequently asked questions

How do I use Spec Kit with Claude Code?
Install the Specify CLI with uv tool install specify-cli, then run specify init my-project --integration claude, or specify integration install claude in an existing Spec Kit project. Open Claude Code in the project and run the steps as slash commands, starting with /speckit-constitution.
What is the Spec Kit workflow?
For spec-driven development: /speckit-constitution once per project to set principles, then for each feature /speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement, and /speckit-converge, repeating implement and converge until convergence reports Converged. Review each result before the next step.
Where does Spec Kit put its files for Claude Code?
It installs each step as a Claude Code skill at .claude/skills/speckit-<command>/SKILL.md. You invoke them in Claude's chat, for example /speckit-specify.
Why do Spec Kit skills fill up Claude's context?
By default each Spec Kit skill is model-invocable, so its description sits in Claude's context and counts toward the skill-listing budget. Pass --integration-options="--no-model-invocation" to specify init so core command skills only run when you type them.
What is the Spec Kit constitution?
A project-level document of principles, such as code quality, testing, and maintainability standards, that every later step follows. You create it once per project with /speckit-constitution.

Keep reading