Why I write the spec first with OpenSpec

The more code an agent writes for me, the more I have noticed where the real work moves. It is not in the typing anymore. It is in being precise about what I want before anything gets built. An agent will happily produce a confident, well-structured implementation of the wrong thing, and it will do it fast. The expensive mistakes are no longer typos; they are misunderstandings. OpenSpec is the tool that pushed me to fix that at the source, by writing the spec first.

Here is why it has stuck.

The spec is the thing you author now

When the agent handles the code, the document you actually write by hand is the spec. That is a real shift. Instead of describing a feature in a throwaway chat message and hoping the model filled the gaps the way I would have, I write down what the change should do, why, and what counts as done. The agent implements against that. The intent lives in a file, not in a conversation that scrolls away.

That reframes the whole loop. The spec is what I craft and keep; the prompt is just disposable instruction that produces it.

Review the idea before you review the diff

A spec is cheap to change. A pull request is not. When I read a one-page proposal and realize the approach is wrong, I have lost a paragraph. When I realize it three hundred lines into a diff, I have lost the diff, the agent’s time, and the focus it takes to untangle code that was built on a bad premise.

OpenSpec puts the decision point early, in plain language, where it is cheapest to be wrong. I am reviewing the idea while it is still an idea. By the time I am looking at code, the hard question (is this even the right thing to build?) is already settled.

Change proposals make the work legible

OpenSpec organizes work as change proposals: you propose what should change, align on it, the agent implements it, and the finished change gets archived into the living spec. That flow does two useful things.

First, it gives every non-trivial change a paper trail in words. Six weeks later, “why does it work this way?” has an answer that is not buried in a commit message or lost in a chat history. Second, it keeps the agent on a leash. A proposal is a scope boundary. The model is far less likely to wander into a refactor I never asked for when there is an agreed spec describing exactly what this change covers.

Durable context beats a fresh prompt

Every new agent session starts cold. The spec is the warm context I hand it. Instead of re-explaining the shape of the system in each conversation, the agent reads the specs and starts aligned. The knowledge stops living in my head and my chat scrollback and starts living in the repo, where the next session, or the next tool, can pick it up.

This is the part people underrate. Spec-driven development is not bureaucracy; it is institutional memory that an agent can actually read.

Separating what from how

Code answers how. A spec answers what and why. Keeping them apart means I can reason about the behavior I want without getting pulled into implementation details too early, and I can review a change in the language of the problem instead of the language of the solution. When the what is agreed and written down, the how is the part I am genuinely happy to delegate.

The point

Spec-driven development is not about slowing down. It is about moving the slow, careful thinking to the front, where it is cheap, and letting the agent run fast on the part it is good at. OpenSpec gives that discipline a shape: write the spec, agree on it, then build. The same instinct runs through everything I have written here lately, that when a machine is doing the writing, the leverage is in being clear, strict, and explicit up front.

It pairs naturally with why I reach for Go in an agentic workflow: a small, predictable language and a clear, agreed spec are the same bet made twice, on the language and on the process. If you want to see what comes out the other end, here’s what I’m shipping.