Spec Kit: the spec comes before the agent

Most of us still use coding agents the way we use a chat window. You write three lines of prompt, the agent starts touching files, you read the diff and correct it. On a small change that works fine. On a feature that touches the database, the API and the interface it starts to come apart, and the breaking point is always the same: the decisions live in the conversation, and the conversation dies when you close the session. Two weeks later you open the code and you no longer know why that table has three states instead of two.

Spec Kit is GitHub's attempt to put some order into this. It is open source, MIT licensed, and the first thing worth saying is what it is not: it is not a framework, it does not end up in your dependencies, it does not run at runtime. It is a CLI that drops templates, scripts and a set of slash commands for your agent into your repository. You install it, and what changes is the process, not the stack.

uv tool install specify-cli
specify init my-project

From that point you have a .specify/ folder with the templates and the project memory, and the commands available inside your agent. I use it with Claude Code, but the supported integrations are dozens by now, from Copilot to Cursor to the Gemini CLI.

The flow, concretely

These are the commands I actually use, in order:

/speckit.constitution   project principles and constraints, written once
/speckit.specify        what the feature must do, without saying how
/speckit.clarify        the questions about the vague parts, before the plan
/speckit.plan           stack, architecture, data model, contracts
/speckit.checklist      the quality checklist on the requirements
/speckit.tasks          the ordered task list
/speckit.analyze        consistency check across spec, plan and tasks
/speckit.implement      execution

What comes out is not a chat, it is a folder. For every feature you end up with something like this:

specs/009-accounting-module/
├── spec.md            requirements, user scenarios, success criteria
├── research.md        the alternatives considered and why
├── data-model.md      entities, relations, constraints
├── contracts/         the API interfaces
├── plan.md            how it gets built
├── tasks.md           numbered tasks, in dependency order
└── checklists/        what has to be true for the feature to be done

Plain text files inside the repository, versioned next to the code. That is the part that matters more than any of the others.

The constitution is the part I had underestimated

At first I treated /speckit.constitution as a ceremonial step, the place where you write four good intentions nobody will ever read again. I was wrong. The constitution of one of the projects I am working on now is a 14 KB file split into core principles, platform constraints, development workflow and governance. It holds the things that are no longer up for discussion on that project: how authentication is done, what must never reach the logs, which libraries have already been chosen and why, when a migration is required.

It does one specific job. Without it every feature starts from a blank page and the agent redesigns the stack from scratch, with the confidence of something that has no memory of last time. With the constitution in context the proposals that come back are already inside the project's rails, and on the rare occasions they are not, you notice immediately because you have a text to compare them against.

What I get out of it

The spec outlives the session

Six months later spec.md is still there, with the scenarios, the success criteria and the assumptions I put into it. Nobody has the chat history and nobody rereads it. When someone new joins the project I do not hand them the conversation, I hand them the folder.

The ambiguity surfaces before the code exists

/speckit.clarify is the command that surprised me most. It asks the awkward questions about the parts you left vague, and it asks them when answering costs nothing. What happens if the user cancels halfway through? Do we recalculate the total or freeze it? The specs I write now have a Clarifications section that is the minutes of those questions, and it is the piece that has saved me the most hours.

A feature becomes a list, not a block

The last tasks.md I generated has 64 checkbox items, ordered by dependency. The work can be interrupted, picked up the next day, split across different sessions, and at any point you know where you are. With a prompt in a chat you know that only for as long as you stay in that chat.

Review becomes possible again

You can read a spec in ten minutes and argue about it. A two thousand line diff produced in one go does not get reviewed with the same attention by anyone, and whoever says otherwise has never done it on a Friday evening. Moving the quality control ahead of the generation is the only way I have found not to sign pull requests I have not understood.

What it costs

The full flow, before a single line of code gets written, is comfortably forty-five minutes. For a two line fix, for a bug, for an experiment I will probably throw away, I do not use it and I would not recommend it. The cost pays for itself when the feature is large enough to have a data model, or long enough to outlast one session.

There is also a risk I have run into. The agent writes the spec, and the spec is long: the one for that accounting module is a 27 KB file. If you do not actually read it, you have only moved the problem, because now you are approving a document you do not understand instead of a diff you do not understand. The answers to /speckit.clarify have to come from me, the model cannot guess them, and every time I rushed those answers the result was worse.

One practical note to close on: the project moves fast and the commands have been renamed at least once, so before copying anything from an old tutorial it is worth opening the repository. That is not a complaint, it is the normal life of a tool that came out recently and has a lot of people on it.

These days I run Spec Kit on anything that lasts longer than half a day. Not because I enjoy writing documentation, which is something I avoided for years, but because it is the only way I have managed to put an agent on something big without losing control of it.