Spec-driven development

OpenSpec is how I stopped losing intent when a large language model (LLM) writes code. The diff arrives fast; the decisions evaporate by the next session. I stopped fighting that with longer prompts and started using OpenSpec — an open-source framework from Fission AI that forces every change to begin as a specification, not a chat.

Contents

1. What OpenSpec adds to spec-driven development
2. The OpenSpec workflow I actually run
3. Small features or nothing
4. The open questions are the point
5. Documentation as a by-product
6. What changed for me
7. What it does not solve
8. References

What OpenSpec adds to spec-driven development

Specification-driven development is an old idea: write down what the software should do, and let that document be the source of truth while you build. LLMs made code cheap, and the bottleneck moved from can this be built to is this what I meant. A written specification becomes the one artefact an LLM cannot drift away from, because every prompt starts from it.

I implement this with OpenSpec. Specs live next to the source code, changes are proposed as deltas against them, and nothing merges into the source of truth until it has actually shipped.

The OpenSpec workflow I actually run

Every OpenSpec change moves through four stages:

In OpenSpec, Explore is a conversation with no code — the LLM reads the software codebase and challenges the idea. Propose turns the surviving idea into a proposal, a design doc, delta specs, and a task list. Apply is implementation, checkbox by checkbox. Archive merges the deltas into the living specs and files the change away.

A recent example on this personal site: I wanted a flag to keep certain posts out of the gallery. Explore found a latent bug in how that gallery was loaded, so the proposal grew from “add a flag” to “add a flag and fix the loader”. Without that OpenSpec stage I would have shipped both.

Small features or nothing

Almost every change I ship this way is tiny. That is the point. A change small enough to describe in one proposal is small enough for the LLM to hold while implementing, and small enough for me to review properly. When one turns out to be a bad idea, throwing it away costs almost nothing.

The alternative is the sprawling prompt that asks for a feature with five concerns baked in. The LLM obliges. What comes back is a diff nobody can honestly review.

The open questions are the point

The part I value most is that OpenSpec’s propose stage flags what it cannot decide. An LLM can argue both sides all day. It cannot know what I want — so it asks, I answer, and the decision is recorded before any code is written.

That keeps the judgement with me and the typing with the LLM.

Documentation as a by-product

I have never sat down to document these projects. They are documented anyway. Each shipped OpenSpec change leaves behind specs and an archive entry — the why, the decisions, the task list. When I open a fresh LLM session, it reads the specs and knows the rules without me re-explaining anything. The model still starts cold; the written specification is what makes that stop mattering.

Even the writing goes through the OpenSpec workflow. The post about turning request logs into Cloudflare WAF rules and the one about optimising a Google Cloud Build pipeline each started as a proposal. So did the post you are reading.

What changed for me

Since I picked up OpenSpec, I have not hand-written a line of code on my side projects. Every change starts as a proposal and comes out as a diff I read and either accept or send back. My time went from typing syntax to deciding what should exist.

Any new side project I start now begins the same way: explore first, specification before code. One weekend this year I used the OpenSpec workflow on an idea I had wanted to build for years. By Sunday night I had a working MVP — built the same way as the tiny changes, just stacked back to back.

What it does not solve

The ceremony is real. A one-line fix does not deserve a full proposal, and giving it one anyway wastes time. Specs stay alive only if you keep archiving. And nothing in the OpenSpec workflow verifies anything: a wrong idea written as a specification is still wrong. I still read every diff before it lands.

What it buys me is simple: when the LLM and I disagree, we disagree about something small, early, and written down.

References

• OpenSpec — by Fission AI
• Specification-driven development — Wikipedia
• Large language model — Wikipedia
• GitHub Spec Kit — related tooling in the broader spec-driven movement