GitHub's New Spec-Kit: A Better Way to Talk to Your AI Coding Assistant

You know the feeling. You’re working with an AI coding agent—maybe GitHub Copilot, maybe Claude—and you ask it to build a new feature. You describe what you want, and boom, a block of code appears. It looks right. It even compiles. But when you run it, you realize it subtly missed the entire point.

We’ve all been there. I call it “vibe-coding.” We’re basically giving the AI the general vibe of what we want and hoping for the best. It’s fine for a quick prototype, but when you're building something serious or trying to modify a complex, existing codebase, it starts to fall apart.

Here’s the thing: GitHub thinks we’ve been looking at this all wrong. The problem isn’t the AI’s coding ability. The problem is us. We’re treating these powerful tools like a search engine, when we should be treating them like a junior pair programmer—one who is incredibly fast and great at spotting patterns, but also incredibly literal. They need crystal-clear instructions.

To fix this, GitHub just open-sourced a new project called Spec-Kit. It’s a toolkit designed to bring a more structured approach, called Spec-Driven Development (SDD), to our AI workflows. And people are paying attention—it’s already one of the fastest-growing dev tools on GitHub right now.

So, let's break down what this is all about.

What Exactly is Spec-Driven Development?

Okay, I know what you might be thinking. "Specs? Isn't that just a fancy word for those massive, boring requirements documents nobody ever reads?"

Not quite.

Spec-Driven Development, or SDD, flips the usual process on its head. Instead of the spec being a loose guide for the code, the spec becomes the absolute source of truth. The code exists to serve the spec, not the other way around.

Think of it like this: Vibe-coding is like telling a chef to "make me something tasty for dinner." You might get pasta, you might get a sandwich. Who knows?

SDD is like handing that chef a detailed, step-by-step recipe. The recipe dictates the outcome.

In practice, this means you start by writing a clear, structured specification. You focus on the what and the why of what you're building, without getting bogged down in the technical details just yet. Then, you feed that spec to your AI coding agent. It becomes the grounding document that the AI uses to generate, test, and validate every line of code.

The result? Less guesswork, fewer "oops, that's not what I meant" moments, and code that actually does what you intended. This isn't about bringing back waterfall development or creating more bureaucracy. The spec is a living thing that you update as you go.

So, What’s Actually in the Box?

Spec-Kit isn’t just a concept; it’s a tangible set of tools. It really comes down to two main things:

1. The specify CLI: This is a little command-line tool that gets your project set up for SDD. It downloads the right templates for whatever AI agent and platform you're using.
2. Templates & Scripts: This is the heart of it. Spec-Kit gives you a foundational structure for what a spec looks like, how to create a technical plan, and how to break it all down into small, bite-sized tasks that an AI can actually understand and execute.

The CLI is written in Python (you'll need 3.11 or newer). Once you have it installed, you get access to a set of simple "slash commands" that you run right inside your AI agent's chat interface.

Here are the core commands that make up the workflow:

• /speckit.constitution: This is where you set the non-negotiable rules for the project. Think of it as your project's Ten Commandments.
• /speckit.specify: You describe what you want to build and why. No tech stack talk allowed here!
• /speckit.plan: Now you bring in the tech stack. The AI takes your spec and generates a technical implementation plan.
• /speckit.tasks: The AI breaks that plan down into a checklist of actionable, ordered tasks.
• /speckit.taskstoissues: (Optional) This handy command turns that task list into actual GitHub issues for easy tracking.
• /speckit.implement: You give the green light, and the AI gets to work, executing the tasks one by one.

There are also a few optional commands to help you catch problems early, which I highly recommend:

• /speckit.clarify: Before you make a plan, this command has the AI ask you clarifying questions to fill in any gaps in your spec. Super useful for avoiding rework later.
• /speckit.analyze: After you have a task list, this checks for consistency. Does every requirement in the spec have a corresponding task? Does the plan match the spec?
• /speckit.checklist: This generates a custom checklist to help you manually verify that your spec is clear, complete, and consistent. Think of it like unit tests for your requirements.

One of the coolest parts is that constitution.md file. It's where you put your "standing instructions"—things like "always use TypeScript," "all endpoints must have tests," or "stick to our company's design system." You write it once, and the AI refers to it forever.

A Step-by-Step Guide: Let's Build Something with Spec-Kit

Alright, let's walk through how you'd actually use this. Imagine we're building a simple photo album app.

Step 1: Get Your Tools Ready

Before you start, you'll need a few things on your machine:

• Python 3.11+
• uv (the recommended package installer) or pipx
• Git
• A supported AI coding agent (it works with a ton of them, like Copilot, Claude, Gemini, and more)

Step 2: Install the CLI

You'll install the specify-cli tool directly from the official GitHub repo. Be sure to grab the latest version tag from their Releases page.

# Recommended install with uv (replace vX.Y.Z with the latest tag)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

After it's installed, just run specify version to make sure it's working.

Step 3: Initialize Your Project

Navigate into your project folder and run the init command. The CLI is smart enough to detect which AI agent you're using and set everything up for you.

# Create a new project in a new folder
specify init my-photo-app

# Or initialize inside an existing directory
specify init .

This will create a .specify/ directory in your project, which holds all the specs, plans, and templates.

Step 4: Write Your Constitution

Now, inside your AI agent's chat, you'll run your first Spec-Kit command. This only needs to be done once for the entire project.

/speckit.constitution
Create principles for a photo app:
- All code must be in TypeScript.
- Test coverage must be above 90%.
- We will only use local storage, no third-party upload services.
- Adhere to the Material Design system for all UI components.

This creates your constitution.md file, the rulebook for the AI.

Step 5: Describe Your App (The Spec)

Time to tell the AI what to build. Remember, focus on the "what," not the "how."

/speckit.specify
Build an application that organizes photos into albums. The main page shows albums grouped by date. Users can drag and drop albums to re-organize them. Clicking an album opens a tile view of the photos inside. Users can rename and delete albums, but not individual photos from the album view.

The AI will generate a spec.md with user stories and functional requirements.

Step 6: (Optional but Smart) Clarify and Validate

Before moving on, it’s a good idea to run the quality commands.

# First, ask the AI to find any gaps
/speckit.clarify

# Then, check the spec for clarity and completeness
/speckit.checklist

The AI might ask you things like, "Is there a limit to how many photos can be in an album?" or "Should drag-and-drop work on mobile?" Answering these now saves you a massive headache later.

Step 7: Define the Tech Stack (The Plan)

Now you can get technical. Tell the AI how you want to build it.

/speckit.plan
Use Vite with vanilla HTML, CSS, and JavaScript. For the backend, use a lightweight Express server with a local SQLite database to store metadata. Use the native HTML5 Drag and Drop API for re-ordering.

This generates several files, including plan.md, data-model.md, and research.md.

Step 8: Break It Down into Tasks

Let the AI create the to-do list.

/speckit.tasks

This produces a tasks.md file with a dependency-ordered list of every single step needed to build the app. It'll even mark tasks that can be done in parallel with a [P]. And if you want, you can turn these into GitHub issues automatically:

/speckit.taskstoissues

Step 9: (Optional) Run a Final Check

One last sanity check before writing code. This makes sure your spec, plan, and tasks are all aligned.

/speckit.analyze

It will flag any inconsistencies, like a user story that doesn't have a task or a database table that was never defined.

Step 10: Let the AI Build It!

With everything perfectly defined, it's time for the magic.

/speckit.implement

The AI will now read the tasks.md file and start executing the plan, step by step, right on your machine. It will run npm commands, create files, and write the code, all while following the rules you set in the constitution.

And that's it! When you want to add a new feature, you just start the process over from Step 5.

Who Is This For, Really?

Spec-Kit is an experiment, but it’s a powerful one. It seems best suited for a few scenarios:

• Greenfield Projects: Starting a new app from scratch? This is perfect. You can lay a solid foundation from day one.
• Large Features: When you're adding a significant new piece of functionality to an existing app, SDD can help you keep things organized and on track.
• Legacy Modernization: Got an old system where the original intent has been lost to time? You can use SDD to capture the essential business logic in a new spec and let the AI rebuild it on a modern stack, leaving the technical debt behind.

It's probably overkill for tiny bug fixes, but for anything substantial, it represents a much more deliberate and reliable way to work with AI. Instead of a fuzzy conversation, you’re having a precise, structured dialogue with your coding partner. It’s a shift in mindset, but it’s one that could lead to much better results.