📐Write the spec, not the code · spec-driven development with GitHub Spec Kit

The moment · when "just tell it what you want" stops working

At first vibe coding is magical. You talk to the AI, a screen appears, it works, you applaud. But there comes a point — almost always around the fifth or sixth feature — where the magic breaks. You ask for a small change and something you never touched falls over. You explain how the login is supposed to work for the third time "because it forgot." You open the project the next day and even you don't know why half the files exist. That's the moment: when the conversation stops being enough as a source of truth, and you need something sturdier than a chat with the memory of a goldfish.

Spec-Driven Development (SDD) is born exactly there. The idea is so simple it's almost offensive: before the AI writes a single line of code, you write down what the app should do — clear, organized, and saved to a file. That document, the spec, becomes the single source of truth. And from it, the agent generates a plan → a task list → the code. In that order. With your checkpoints in between.

The pain · where the Frankenstein comes from

The problem isn't that the AI is dumb. It's that the AI has no memory of intent. On every message it makes the best decision for that message, with no complete picture of what you're building or why. You have that picture in your head — but your head isn't a document the agent can read. So the AI fills the gaps by guessing, and it guesses differently every time. One time the cart saves taxes, another time it doesn't. One time the user can edit their profile, another time the feature vanishes in a refactor. Nobody lied: there simply never was a contract that said what's correct.

What happens if you don't fix this? It's not the apocalypse — it's a slow-motion accident. You end up with an app that almost works, impossible to explain to another person (or to next week's AI), where every fix carries its own odds of breaking something else. And those odds don't forgive: in a blog from this same series we walked through the math of 27% — an agent that's 85% right at each step only completes an eight-step flow 27% of the time (0.85⁸), because the hits multiply, they don't add up. Building blind chains together fragile steps in exactly the same way. The spec is what breaks that chain of fragility: it gives the AI a fixed point to verify each step against, instead of letting every step ride on the luck of the one before.

The solution · you flip the order (spec first, code after)

In vibe coding the flow is: you talk → code → (sometimes) you document. In SDD it flips completely: you specify → you plan → you generate tasks → code. Documentation stops being the forgotten leftover at the end and becomes the starting point. And it's not bureaucracy: each phase is an artifact the agent generates almost by itself from the previous one, with a checkpoint where you approve before moving on. You direct; the AI executes.

The tool · GitHub Spec Kit

You don't have to invent this flow by hand. GitHub Spec Kit is an open source toolkit — from GitHub, free, MIT license — that installs SDD as a series of commands inside your AI agent. You write the spec in natural language; it gives you the structure, the checkpoints, and the commands for the AI to turn it into an app. It's one of the fastest-growing AI tools out there: 122,000 stars on GitHub, and its latest stable release, v0.13.0, shipped on July 17, 2026. It integrates 30+ agents — Claude Code, GitHub Copilot, Cursor, Gemini CLI, and whichever one you use.

Installation · two commands and you're in

Spec Kit installs with uv, the modern Python package manager (fast, no drama). If you don't have uv, you install it first — one line. Then you install the Spec Kit CLI persistently, and initialize your project by choosing your agent. Don't be scared of the terminal: it's literally these commands, in order, and you won't touch it again for the real work (that happens inside your AI's chat).

# 1) If you don't have uv (Python's package manager), install it:
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2) Install the Spec Kit CLI persistently (pinning the stable version):
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.13.0

# 3) See which agents you can choose (the exact value for the --integration flag):
specify integration list

# 4) Initialize your project by choosing your agent (here, Copilot as an example):
specify init mi-proyecto --integration copilot

# 5) Check whether there's a newer version (changes nothing, just reads):
specify self check

The protocol · Spec Kit's commands, in order

Once initialized, Spec Kit gives you a series of slash commands you type inside your agent. They're not magic: each one asks the AI to generate the next artifact in the flow. Order matters — it's a cascade where each step leans on the previous one. These are the real ones, exactly as they come in v0.13.0:

The real flow · 4 phases with your checkpoints

Put it all together, and this is what a project looks like end to end. Notice that at every boundary you review and approve before the AI moves on. That's the trick: it's not that the AI works alone with no brakes, it's that it works alone between checkpoints you control.

The habit · when to write a spec and when not to

SDD isn't for everything. A one-line change, a color on a button, some copy — for that you just talk to the AI normally and you're done. Writing a spec for that would be like asking for architect's blueprints to hang a picture. The good habit is recognizing the threshold: the moment a task touches more than one file, has business rules, or you're going to come back to it next week — right there, spec first. And from then on, every big new feature is born from a spec, not from an impulse.

The master prompt · kicking off a spec-first project

Here's the one prompt worth memorizing. It's the one you hand your AI (with Spec Kit already initialized) to start off right from minute one: it tells it to first set the constitution, then build the spec with you by asking what's missing, and to not write any code until you approve. Copy it, fill in the [brackets], and paste it to your agent at the start of any serious project.

We're going to build this project with Spec-Driven Development using GitHub Spec Kit, which is already initialized. Do NOT write any code yet. Follow this flow with me, stopping at each checkpoint so I can approve before moving on.

My project is: [describe what you want to build and for whom, in 3-5 sentences].
What it must NOT do / my limits: [e.g. don't store credit cards, must work on mobile, no sensitive data in logs].

STEP 1 — CONSTITUTION. First of all, run /speckit.constitution and propose the inviolable principles for this project (security, input validation, consistency, whatever applies). Show them to me and wait for my sign-off.

STEP 2 — SPEC. Then run /speckit.specify and draft the specification from my description: clear requirements and user stories. After that run /speckit.clarify and ask me ALL the questions needed to eliminate ambiguity — don't guess, ask me. Don't move on until I say the spec is correct.

STEP 3 — PLAN AND TASKS. With the spec approved, run /speckit.plan and propose the stack and architecture (explain to me in plain terms why you chose each thing). Then /speckit.tasks for the breakdown, and /speckit.analyze to verify spec, plan, and tasks don't contradict each other. Show me everything and wait for my approval.

STEP 4 — IMPLEMENT. Only when I authorize it, run /speckit.implement and build. When you're done, generate a /speckit.checklist to validate that what was built meets the spec.

Golden rule throughout the process: the spec is the single source of truth. If any of the code drifts from the spec, the spec wins — or you flag it so we update it together. Never change behavior silently.

The easiest paths · what you do by chat and what by command

So you don't get lost: almost everything happens by talking to your AI. You touch the terminal exactly once (install and initialize). The /speckit.* you type inside your agent's chat, like any other message. And the spec you write in your own words — not in code. Here's the split:

Where this comes from (this series' evolution)

If you've followed the library, this doesn't sound new — it's the next step up. The C-A-R protocol taught you to separate building from auditing so you don't ship bugs. The design system resource taught you to lock the visual rules before the first screen. Both share one idea: decide the contract before you execute. SDD takes that idea to its purest form: the spec is the contract, and it's the single source of truth for the whole app — design, logic, behavior. You go from "organize your context" to "write the contract and let the AI fulfill it."