DEV Community

Cover image for Spec Kit: How to Use It with Claude, Codex, and Gemini Without Turning Your Project into…
مصعب يوسف
مصعب يوسف

Posted on Originally published at ms3byoussef.medium.com on

Spec Kit: How to Use It with Claude, Codex, and Gemini Without Turning Your Project into…

#cleancode #softwaredevelopment #flutter #githubspeckit

Spec Kit: How to Use It with Claude, Codex, and Gemini Without Turning Your Project into AI-Flavored Chaos

Spec Kit: How to Use It with Claude, Codex, and Gemini Without Turning Your Project into…

Most AI-assisted coding goes wrong in a very predictable way.

A developer has an idea.

They open Claude, Codex, or Gemini.

They type something like:

Build me a full ERP with auth, dashboard, CRM, reports, mobile app, and clean architecture. creasingly supports persistent, file-based planning.

And how to install it in your IDE with Cursor and Google Antigravity

Most people use AI coding tools backwards.

They open Claude, Codex, or Gemini, throw in a large ambition like “build my ERP,” and expect the model to invent requirements, architecture, implementation order, and quality standards on the fly. Then they act shocked when the result is half impressive and half structurally cursed. A timeless human tradition.

If you want AI to help you build serious software, you need a better operating model.

That is where Spec Kit comes in.

Spec Kit is an open-source toolkit for spec-driven development. Its purpose is not to help you vibe-code faster. Its purpose is to help you move from vague intent to structured artifacts: principles, specifications, technical plans, and task breakdowns. The project explicitly frames this as a way to focus on product scenarios and predictable outcomes instead of improvising everything directly in code, and its workflow is built around the idea that the specification is the source of truth.

This article covers:

  • what Spec Kit actually is
  • why it works better than pure ad hoc prompting
  • how to use it with Claude, Codex, and Gemini
  • how to install it in an IDE workflow with Cursor
  • how to use it with Google Antigravity
  • and how to avoid turning a good methodology into decorative process theater

What Spec Kit actually is

Spec Kit is not “an AI that writes code.”

It is a toolkit and workflow that helps you create a structured development path before implementation. Its official flow centers on commands such as:

  • /speckit.constitution
  • /speckit.specify
  • /speckit.plan
  • /speckit.tasks
  • plus optional commands like /speckit.clarify, /speckit.analyze, and /speckit.implement

Those commands are not random conveniences. They map to a real delivery sequence:

  1. define principles
  2. define what you want to build
  3. clarify ambiguities
  4. create a technical plan
  5. break work into tasks
  6. implement in controlled steps

That is the entire point.

Instead of asking an AI model to simultaneously guess the product, the architecture, the constraints, and the implementation path, you give it a progressively refined set of documents and decisions.

That changes the quality of everything that follows.

Why Spec Kit matters

AI coding tools are strongest when the problem is already shaped.

They are much weaker when they are expected to invent the shape while also doing the work.

Spec Kit solves that by separating intent from implementation. The official docs explicitly emphasize establishing project principles, creating a spec that focuses on the what and why, then creating a technical plan, and only after that generating tasks for implementation.

That gives you several advantages:

  • less ambiguity
  • less repeated context in chat
  • better consistency across sessions
  • easier collaboration across people or agents
  • cleaner implementation sequencing
  • less “the AI sort of understood what I meant” nonsense

In other words, Spec Kit is useful because it turns your project from a stream of prompts into a set of living artifacts.

The core Spec Kit workflow

A good Spec Kit workflow looks like this:

1. Constitution

Define the project’s governing principles. The official docs recommend using /speckit.constitution first so the project has stable development guidelines that the agent can reference during later phases.

Example:

/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements.
Enter fullscreen mode Exit fullscreen mode

2. Specify

Describe what you want to build and why. The official guide explicitly says to focus on the product and user outcomes here, not the tech stack.

Example:

/speckit.specify Build a multi-tenant clinic operations platform for small and medium medical centers. It must support appointments, billing, inventory, staff management, and patient records.
Enter fullscreen mode Exit fullscreen mode

3. Clarify

Use /speckit.clarify to surface ambiguity before architecture hardens. The command is documented as a way to clarify underspecified areas and is recommended before planning.

Example:

/speckit.clarify Focus on tenant isolation, permissions, offline needs, reporting requirements, and auditability.
Enter fullscreen mode Exit fullscreen mode

4. Plan

Now introduce the technical stack and architecture choices. The official docs describe /speckit.plan as the phase where you provide your tech stack and architectural approach.

Example:

/speckit.plan Use Nuxt 4 for frontend, NestJS with Fastify for backend, PostgreSQL as primary database, Redis for queues and caching, and Flutter for mobile.
Enter fullscreen mode Exit fullscreen mode

5. Tasks

Break the plan into executable units. /speckit.tasks exists specifically to generate actionable task lists from the implementation plan.

Example:

/speckit.tasks Break this into backend, frontend, mobile, contracts, testing, and deployment tasks. Prioritize smallest safe implementation order.
Enter fullscreen mode Exit fullscreen mode

At that point, the AI tool is no longer improvising a product. It is executing against a defined plan.

Which, embarrassingly, is how engineering was always supposed to work.

How to install Spec Kit properly

Spec Kit’s official prerequisites are:

  • Linux, macOS, or Windows
  • a supported AI coding agent
  • uv
  • Python 3.11+
  • Git

Recommended install

The official repository recommends installing the Specify CLI directly from the GitHub repo via uv tool install, and explicitly warns that packages with the same name on PyPI are not the official maintained distribution.

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
specify version
specify check
Enter fullscreen mode Exit fullscreen mode

If you do not want a persistent install, the docs also support one-shot usage with uvx.

uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <PROJECT_NAME>
Enter fullscreen mode Exit fullscreen mode

Initialize in an existing project

The official docs show both specify init . and specify init --here, and allow you to choose an AI agent during setup or specify it directly.

specify init --here --ai claude
Enter fullscreen mode Exit fullscreen mode

Or with one-shot usage:

uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --ai claude
Enter fullscreen mode Exit fullscreen mode

After initialization, your AI agent should have access to the Spec Kit workflow commands.

How Spec Kit integrates with Claude, Codex, Gemini, Cursor, and Antigravity

Spec Kit now supports a wide set of AI coding agent integrations. The official integrations guide says specify init or specify integration install sets up the right command files, context rules, and directory structure for the selected agent. The supported table includes Claude Code, Codex CLI, Gemini CLI, Cursor, and Antigravity (agy) among many others.

The important details are:

  • Claude Code uses a skills-based integration and installs skills into .claude/skills
  • Codex CLI uses a skills-based integration and installs skills into .agents/skills; those are invoked as $speckit- rather than slash commands
  • Cursor uses the integration key cursor-agent
  • Antigravity uses the integration key agy and installs a skills-based integration automatically
  • CLI-based agents such as Claude Code and Gemini CLI require the tool itself to be installed, while IDE-based integrations such as Cursor work through the IDE environment.

That distinction matters because installation is not identical across tools.

Using Spec Kit with Claude

This is one of the most natural pairings.

Spec Kit’s workflow lines up very well with Claude Code’s agentic, repo-aware model. Anthropic positions Claude Code as a coding agent that can read code, edit files, run commands, and work across terminal and IDE environments, which makes it especially good at moving from spec artifacts to controlled implementation steps.

Recommended setup 

specify init --here --ai claude
Enter fullscreen mode Exit fullscreen mode

Because Claude’s integration is skills-based, Spec Kit installs the relevant skills into .claude/skills.

Best way to work

Use Claude for:

  • constitution drafting
  • requirements shaping
  • ambiguity clarification
  • architecture planning
  • implementation of one task at a time

A strong workflow looks like this:

/speckit.constitution Define project principles for modularity, testing, API boundaries, and performance.
Enter fullscreen mode Exit fullscreen mode 
/speckit.specify Build a workspace-based project operations platform for internal teams and client collaboration.
Enter fullscreen mode Exit fullscreen mode 
/speckit.clarify Focus on permissions, reporting, team ownership, and workspace isolation.
Enter fullscreen mode Exit fullscreen mode 
/speckit.plan Use Nuxt 4, NestJS with Fastify, PostgreSQL, Redis, and Flutter for mobile.
Enter fullscreen mode Exit fullscreen mode 
/speckit.tasks
Enter fullscreen mode Exit fullscreen mode

Then, after the documents exist:

Implement only Task 1 from the Spec Kit task list.
Do not expand scope.
Summarize changed files, checks run, and follow-up risks.
Enter fullscreen mode Exit fullscreen mode

Claude is especially strong in the specification, clarification, and planning phases because it handles long-form reasoning and structured refinement well. The combination works because Spec Kit gives Claude durable project truth instead of asking it to re-invent the project in every session.

Using Spec Kit with Codex

Codex is better thought of as a strong execution partner once the project intent is already defined. OpenAI describes Codex as an AI coding agent for planning, building features, refactoring, reviewing code, and operating in real engineering workflows, with gpt-5.4 recommended as the starting point for most tasks.

The practical rule is simple:

Let Spec Kit define the truth. Let Codex execute against it.

Because Codex’s Spec Kit integration is skills-based and installs into .agents/skills, the command style differs from slash-command agents. The official Spec Kit docs note that while most agents use /speckit.*, Codex CLI in skills mode uses $speckit-* instead.

Recommended setup 

specify init --here --ai codex --ai-skills
Enter fullscreen mode Exit fullscreen mode

Suggested workflow

  1. Create the constitution, spec, plan, and tasks
  2. Ask Codex to read them before coding
  3. Implement only one task at a time

Example:

Read the current specification, plan, and tasks for this feature.
Do not code yet.
Enter fullscreen mode Exit fullscreen mode 
Return:
1. implementation dependencies
2. risky areas
3. smallest safe first task
Enter fullscreen mode Exit fullscreen mode

Then:

Implement only Task 1 from the approved Spec Kit tasks.
Keep the patch narrow.
Run relevant checks.
Summarize changed files and follow-up risks.
Enter fullscreen mode Exit fullscreen mode

That keeps Codex focused on execution rather than wasting cycles trying to discover the product’s intent from scattered chat context.

Using Spec Kit with Gemini

Gemini works well with Spec Kit too, especially when you treat Spec Kit artifacts as the stable project reference.

The official Spec Kit integrations list includes Gemini CLI as a supported agent.

Recommended setup 

specify init --here --ai gemini
Enter fullscreen mode Exit fullscreen mode

Then use the same artifact-driven workflow:

  • create constitution
  • create spec
  • clarify
  • plan
  • tasks
  • implement in phases

Example:

Read the specification, clarification notes, technical plan, and task list in this repo.
Do not code yet.
Enter fullscreen mode Exit fullscreen mode 
Return:
1. architecture understanding
2. dependency order
3. likely risks
4. best first milestone
Enter fullscreen mode Exit fullscreen mode

Then:

Implement only the first milestone from the task list.
Keep changes minimal.
Report modified files, checks, and follow-up tasks.
Enter fullscreen mode Exit fullscreen mode

The key is the same: Gemini should not be improvising the project. It should be working from artifacts.

How to install Spec Kit in Cursor

Now to the part people usually skip and then complain about for an hour.

Cursor has official support in Spec Kit, but the correct integration key is cursor-agent, not cursor. The current Spec Kit integrations guide explicitly lists Cursor under cursor-agent.

Cursor itself documents Rules for persistent instructions and Skills for reusable workflows, which makes it a good home for spec-driven work rather than just raw prompting. Cursor’s docs describe Rules as project, team, and user-level persistent guidance, and Skills as reusable workflows Agent can follow for specific tasks.

Install Spec Kit in a Cursor project

Open your project root in Cursor, then run:

specify init --here --integration cursor-agent
Enter fullscreen mode Exit fullscreen mode

If you are using one-shot install:

uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --integration cursor-agent
Enter fullscreen mode Exit fullscreen mode

You can also initialize and let Spec Kit prompt you for the agent selection.

What Cursor gets

Spec Kit installs the right command or skill files and directory structure for the Cursor integration. Cursor’s own model supports persistent project rules and reusable skills, so this fits naturally into a spec-driven workflow.

Practical workflow inside Cursor

Use Cursor Rules for:

  • architecture constraints
  • naming conventions
  • layer boundaries
  • “what not to do”

Use Spec Kit for:

  • constitution
  • specs
  • planning
  • task generation

Use Cursor Agent for:

  • implementing one task
  • reviewing a diff against the plan
  • tracing data flow or service boundaries
  • verifying the patch after execution

A good loop in Cursor looks like this:

  1. create project Rules
  2. run Spec Kit to generate artifacts
  3. ask Agent to implement Task 1 only
  4. verify
  5. move to the next task

That is much stronger than asking Cursor Agent to “build the whole feature” from thin air and hoping the vibes hold.

How to use Spec Kit with Google Antigravity

Google introduced Antigravity as an agentic development platform designed to let developers operate at a more task-oriented level, with agents that can plan, execute, and verify work across the editor, terminal, and browser. The official launch post describes two surfaces: a hands-on editor view and a manager surface where multiple agents can be orchestrated for larger tasks.

Spec Kit supports Antigravity directly under the integration key agy, and the integrations guide notes that this is a skills-based integration whose skills are installed automatically.

Install Spec Kit for Antigravity

Inside the project root:

specify init --here --integration agy
Enter fullscreen mode Exit fullscreen mode

Or with one-shot usage:

uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --integration agy
Enter fullscreen mode Exit fullscreen mode

Why this pairing makes sense

Antigravity is built around autonomous task orchestration. Spec Kit gives that orchestration a structured, artifact-backed workflow:

  • constitution for principles
  • spec for product intent
  • clarify for ambiguity removal
  • plan for architecture
  • tasks for execution order

That means Antigravity agents are not just working from a prompt. They are working from project artifacts.

And that is exactly what agentic systems need if you want them to behave like engineers instead of enthusiastic raccoons in a codebase.

Best use of Spec Kit in Antigravity

Use Antigravity for:

  • larger multi-step feature execution
  • verification passes
  • long-running implementation tasks
  • agent-reviewed UI or cross-tool workflows

Use Spec Kit to define the artifacts those agents should follow.

That combination is strong because Antigravity is optimized for agent orchestration, while Spec Kit is optimized for intent clarity and structured development phases.

A practical installation sequence for your IDE workflow

If you want the cleanest setup in a real project, do this:

Step 1: Install the CLI 

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
specify version
specify check
Enter fullscreen mode Exit fullscreen mode

Step 2: Initialize for your environment

For Claude 

specify init --here --ai claude
Enter fullscreen mode Exit fullscreen mode

For Codex 

specify init --here --ai codex --ai-skills
Enter fullscreen mode Exit fullscreen mode

For Gemini 

specify init --here --ai gemini
Enter fullscreen mode Exit fullscreen mode

For Cursor 

specify init --here --integration cursor-agent
Enter fullscreen mode Exit fullscreen mode

For Antigravity 

specify init --here --integration agy
Enter fullscreen mode Exit fullscreen mode

Supported integrations, keys, and behavior are documented in the official integrations guide.

Step 3: Start the project properly

Run:

  • constitution
  • specify
  • clarify
  • plan
  • tasks

Then implement one task at a time.

That is the whole discipline.

The best way to combine Spec Kit with these tools

If you want the strongest setup, use the tools by role.

Claude

Best for:

  • shaping the product
  • writing principles
  • clarifying ambiguity
  • refining architecture

Codex

Best for:

  • executing defined tasks
  • narrow patches
  • refactors
  • implementation follow-through

Gemini

Best for:

  • artifact-based implementation or review
  • second-opinion planning
  • working in a Gemini-centered environment

Cursor

Best for:

  • interactive IDE implementation with persistent rules and skills
  • spec-driven development inside daily coding flow

Antigravity

Best for:

  • multi-step task orchestration
  • agent-driven execution and verification
  • larger workflow delegation

The mistake is trying to make every tool do every job equally well.

That is not sophistication. That is workflow confusion with branding.

Common mistakes

1. Treating Spec Kit as a document generator

It is not just for producing pretty files. It is for structuring delivery.

2. Writing a weak spec and expecting a strong plan

Garbage in still wins. AI has not repealed that law.

3. Skipping clarify

Unresolved ambiguity becomes implementation drift later.

4. Using giant tasks

If your tasks are still huge, you have not decomposed the work. You have just renamed the mess.

5. Jumping from spec to implementation without artifact review

The point of the method is not to make the AI write faster. The point is to make the project clearer before it writes.

6. Installing the wrong integration

For Cursor, use cursor-agent, not cursor.

For Antigravity, use agy.

That tiny detail has ruined enough afternoons already.

Final thought

Spec Kit is valuable because it forces a healthy separation between:

  • intent
  • clarification
  • architecture
  • tasks
  • implementation

That separation makes Claude better.

It makes Codex more reliable.

It makes Gemini more grounded.

It makes Cursor more disciplined.

And it gives Antigravity agents something real to operate on besides vibes.

The big idea is simple:

Do not ask the AI to invent your project while building it. Use Spec Kit to define the project, then let the AI execute against that truth.

That is the difference between:

  • a flashy session and
  • a system that survives contact with reality

Sources

Spec Kit

Top comments (0)