AI builds. You bring the blueprints

It has probably happened to you: you ask the AI for something, get the result in ten seconds, and discover half an hour later that it understood something else.

AI is an excellent construction crew: fast and tireless. But nobody lets a construction crew decide on its own how your house will turn out. Someone has to bring the blueprints. In software, that’s called Spec-Driven Development (SDD), and this article is what I learned using it every day.

The problem: remodeling your house over WhatsApp voice notes

#

A friend decided to remodel his house. Instead of sitting down with an architect, he sent voice notes to the foreman: “knock down that wall”, “make the kitchen open instead”, “a socket right there where the fridge goes”.

When we do that with AI it’s called vibe coding. You ask over chat, accept whatever comes out and keep adjusting. And it fails just like the voice-note remodel, for three reasons:

• Requests live in the chat. Nobody else sees them, nobody saves them, nobody can review them.
• It comes out different every time. Ask for the same thing twice and you get two different things.
• Memory gets wiped. The chat closes or someone leaves the team, and nobody knows why that wall is there.

The ending? The house turned out similar to what he asked for. But it’s not what he asked for. Software works exactly the same way.

The twist: stop writing prompts, start writing specs

#

A prompt is private, temporary and hard to review. A spec is the same thing you’d ask the AI, but written as a named requirement with a verifiable acceptance criterion, stored in the repository next to the code:

## Requirement: Copy button
The result MUST be copyable as Markdown.
WHEN the input is empty, THEN the button is disabled.

Anyone on the team can read it, discuss it and improve it, today or six months from now.

Prompt-first is fast. Spec-first is repeatable. And in large projects, what scales isn’t start-up speed: it’s repeatability.

From “prompt and pray” (you ask, you pray, you review 800 lines of code) to “specify and verify” (you agree on the WHAT in one or two pages, the AI implements, you verify against the spec). The quality of what the AI produces is proportional to the quality of what you give it.

The mental model: the spec is the contract

#

Nobody builds without codes, blueprints, engineering and a schedule. Neither should AI:

And the step that makes it all work or not: review what the AI generates before any code exists. If you and your team agree with the spec and the plan, the contract guarantees the result. If nobody reads them, we’re back to vibe coding with more folders.

My path: from Spec Kit to OpenSpec

#

Until 2025 I built everything with prompts. When SDD appeared, the first thing I tried was Spec Kit, GitHub’s tool, on a personal project. To be fair: it brought order. But it felt cumbersome, with many files and lots of ceremony, and it burned a lot of tokens. Back then tokens didn’t hurt. Today they do.

Then OpenSpec appeared, with a lighter philosophy, and that’s when I felt the difference. It genuinely sped up three things I do all the time: evolving my apps, modernizing existing applications, and building new ones. Today it’s my day-to-day framework.

OpenSpec in two ideas

#

Idea 1 · Two folders: the truth and what changes.

openspec/
├── specs/      ← how the system works TODAY (source of truth)
└── changes/    ← proposals in progress, one folder per change
    └── add-life-policy/
        ├── proposal.md   what and why
        ├── design.md     technical decisions
        ├── tasks.md      implementation checklist
        └── specs/        the DELTA: which requirements change

In the analogy: specs/ are the house’s up-to-date blueprints; changes/ are the building permits in progress. That’s why it works so well on existing systems: you don’t draw the blueprints for the whole house on day one, you draw the room you’re about to touch.

Idea 2 · Delta specs: describe only what changes. Like an addendum to a contract: you don’t rewrite everything, you only sign what’s added, modified or removed. A reviewer understands the change by reading twelve lines of Markdown, without diving into the code. If the delta is wrong, it gets fixed before a single line exists.

The flow, in four commands from your AI assistant:

1. /opsx:explore — think through the problem with the AI, without committing (optional).
2. /opsx:propose "idea" — the AI generates proposal, delta, design and tasks. You review. No code yet.
3. /opsx:apply — the AI implements, guided by the spec.
4. /opsx:archive — the delta is merged into specs/: the truth is up to date.

The checkpoint is between 2 and 3: you review a few pages of Markdown, not hundreds of generated lines. Setup takes two minutes (npm install -g @fission-ai/openspec@latest and openspec init), it works with 25+ assistants (Claude Code, Cursor, Copilot, Codex, Gemini CLI…) and needs no API keys or servers: it’s pure Markdown in your repo.

And on the other side: Spec Kit

#

Spec Kit is GitHub’s take. Its philosophy is opposite in one key way: a fixed, sequential pipeline of seven steps (constitution → specify → clarify → plan → tasks → analyze → implement), governed by a constitution every agent reads first. Each feature generates its full folder with seven or more files, creates a git branch automatically, and has GitHub’s backing, documentation and tutorials.

One sentence sums up the difference: Spec Kit answers “what are we building for feature 003”; OpenSpec answers “what does our system do”. Over time, one leaves you a collection of features; the other, a living document of the system.

When to use which?

#

OpenSpec if you work on existing code, want a living spec that grows change by change, prefer short cycles and less ceremony, and want to control your own branching strategy.

Spec Kit if you’re starting from scratch, the team is new to SDD and appreciates a fixed pipeline with fewer decisions, you want a strong constitution, and you value GitHub’s ecosystem.

Spec Kit is the on-ramp to SDD; OpenSpec is the destination when specs have to live and grow with the system.

What has to be said honestly

#

This isn’t magic. People who tried it on real code report uncomfortable things:

• A hammer for a nut. A small bug can turn into four user stories with sixteen criteria. OpenSpec helps with a flow without mandatory phases, but the discipline of not over-specifying is still yours. Practical rule: if the spec has more lines than the change, the flow is too heavy for that case.
• A false sense of control. With templates and constitutions, the agent can still ignore instructions. No tool eliminates this: human review between proposing and implementing remains mandatory. The spec reduces the risk; it doesn’t make it disappear.
• It can turn into waterfall if you do too much design up front. The answer is to keep changes small and iterative.

And a nuance for 2026 models: the official guides from OpenAI and Anthropic agree on describing the destination, not the path. Current models plan and self-correct. A well-written spec is exactly that: goal, success criteria, constraints, and how far the agent goes before coming back to you. That’s why it works.

The wheel is yours

#

From “prompt and pray” to specs that live in the repo and get reviewed before the code. What I take with me:

• specs/ is the truth. changes/ is the delta.
• The flow is propose → apply → archive.
• The only non-negotiable: review first.

$ git commit -m "this article"
Author: human <me>
Co-authored-by: AI — implemented the spec, didn't decide it.

That division of roles is the whole point.

My recommendation: pick a small, real feature from your project, run openspec init, and try the full cycle once. It takes less than an hour and you’ll know whether it works for you better than any article, including this one.

References

#

• openspec.dev · github.com/Fission-AI/OpenSpec
• github.com/github/spec-kit
• Birgitta Böckeler, Understanding Spec-Driven Development (martinfowler.com)