Spec-driven development means you write down what to build and why before an AI agent is allowed to touch the code. The spec becomes the source of truth, the agent builds from it and the tests show that the result is right. We rebuilt activator.se this way and the repo now holds just over 50 specs.
Why isn't prompting enough?
You have probably asked an AI agent to build something and got code that looks right but solves the wrong problem. So have we. It is rarely the model. The agent guesses wherever you are vague and it guesses with great confidence.
This way of working is sometimes called vibe coding and it works well for a prototype. It works less well for code that has to live for years, because the requirements exist only in your head and in a chat that disappears. Six months from now nobody on the team can see why the code looks the way it does. That costs you time every time something has to change.
How does spec-driven development work?
The workflow has five steps and each step builds on the one before. You review the result of every step before the agent moves on, so a mistake never gets the chance to grow.
- Spec: what to build and why, with user stories and acceptance criteria that can be tested.
- Plan: how to build it, with technology choices and a data model checked against the rules of the project.
- Tasks: the plan is broken down into small steps in the right order, with the test before the code.
- Code: the agent builds one step at a time until the tests pass.
- Review: a separate agent checks the code against the spec. If a requirement has to change, that happens in the spec as a deliberate decision.
Everything is plain text files in the repo. That means the requirements follow along in version control and are reviewed in the same pull request as the code. If you change model or agent, it is all still there, which is good insurance in a market that moves quickly.
What changes in practice?
When we specified the chat on this site, the question of a daily cost cap came up before any code existed. The security review then found that a handful of addresses could reach the cap and pause the chat for everyone. It became a decision that took a few minutes: a lower cap per visitor.
Had we found the same thing in production, the chat would already have stopped. That is the whole point: what is unclear surfaces as questions before the code is written and not as bugs afterwards.
It may sound like more work, but in practice it goes faster. It is much easier to review two pages of requirements than 800 lines of code. A mistake in the spec costs one sentence to fix, while the same mistake in the code costs an afternoon.
How do you get started with GitHub Spec Kit?
GitHub Spec Kit is a free open source tool that gives your agent the whole workflow as ready-made commands. It works with Claude Code, GitHub Copilot, Cursor and several others. You need Git, Python 3.11 or later and the uv package manager. After that, allow fifteen minutes from installation to your first spec.
- Install the tool:
uv tool install specify-cli - Create the project:
specify init my-project --integration claude - Write the project's constitution once with
/speckit-constitution. These are the rules that always apply. - Describe the need with
/speckit-specifyand let/speckit-clarifyfind what is unclear. - Let the agent plan and build with
/speckit-plan,/speckit-tasksand/speckit-implement.
Pick a small, well-defined feature the first time. It is better to get to know the workflow there than in your most critical system.
Common questions about spec-driven development
Do I need GitHub Spec Kit?
No. You can follow the method with plain text files and any agent. Spec Kit makes it easier because the templates and commands are already there.
Does it work in existing projects?
Yes. Spec Kit can be added to an existing project and the documentation has its own guide for that. Start with a well-defined new feature instead of specifying everything that already exists.
How long should a spec be?
As short as possible, with one spec per feature. If it grows beyond a few pages, it is two features.
Read the whole guide
We have gathered the way of working in the guide Build it right with AI agents. You get a worked example from idea to finished feature, a constitution, a reviewing agent and a hook to copy, plus a plan for your first week. You need no prior knowledge and the examples work in any language and framework.
Once the agent builds the right thing, the next question appears: how do you keep up with more than one at a time? I write about that in When you become the bottleneck. Want to learn the way of working together? We train your team on site, with your own systems as examples.
