Spec-driven development with AI coding agents: what a spec has to do

Posted on Nov 3 • Originally published at halfcycle.ai

Halfcycle is a module that runs a five-layer build method inside your own Claude Code or OpenAI Codex ( npx halfcycle ).

Ask a coding agent for a feature in one sentence and you get a feature. It will be plausible, it will run, and it will contain a dozen decisions nobody made. Which users can see it. What happens when the list is empty. Whether the old endpoint still works. The agent did not skip those questions. It answered them, quietly, with guesses.

Spec-driven development is the practice of making those decisions before the code exists and writing them down where the agent, and whoever reviews its work, can see them. The spec becomes the thing the code is checked against, not a summary written after.

The idea is old. What changed is the cost of skipping it. A person who misreads a requirement finds out the next day. An agent can build the wrong thing completely, with tests, in minutes, and the result looks finished.

A useful spec is short and specific. It answers four questions.

What is this for, and for whom? One or two sentences. If nobody can write them, the feature is not ready to build, and finding that out now is cheap.

What must be true when it is done? These are the acceptance criteria, and they are the heart of it. Each one should be checkable by someone who did not write it: "an empty list shows the invite button", not "handles empty states well". If a criterion cannot fail, it is not doing any work.

What does it touch, and what does it leave alone? The parts of the system this change owns, the parts it depends on, and the things that are explicitly out of scope. Agents are generous. Without a boundary they tidy, refactor and improve their way into code nobody asked them to touch.

What rules hold across the whole product? Some things are true everywhere: every money amount is stored in minor units, every page needs a signed-in user, nothing is deleted without a record. These belong in one place, referred to by every spec, so they are not restated slightly differently twenty times.

A feature spec answers "what does this feature do". It cannot answer "should this feature exist" or "how does it fit with the other eleven". Those questions live a level up.

So spec-driven development, done properly, has layers. A product plan says what the product is for and what is in and out. An architecture says what the parts are and how they talk. A phase plan says which features ship together and in what order. Then each feature gets its spec. Skip the upper layers and every feature spec is locally sensible and globally inconsistent, which is a very common way for an AI-built product to fall apart around its fourth feature.

Most teams that try this and give up hit one of these.

Nobody reads it critically before the build. The person who wrote the spec, or the agent that drafted it, is the worst reviewer of it. Gaps are invisible to their author. A second reader with fresh eyes, asking "what happens when", finds the holes while they still cost a sentence to fix.

Nothing checks the code against it afterwards. A spec with no check at the end is a wish. The acceptance criteria have to be run, ideally as tests written before the code, and the finished phase has to be compared with what the plan said it would deliver. Including the parts that were quietly dropped.

The same weight for every change. A full spec for a copy fix is ceremony, and people stop following a process the week it wastes their time. A one-line spec for a payments change is negligence. The amount of planning has to fit the risk of the change, or the whole practice gets abandoned.

It lives apart from the work. A spec in a wiki that the agent never sees is decoration. It has to be in front of the agent at the step where it matters, and in front of the reviewer when the work comes back.

Notice that three of those four failures are not about the spec at all. They are about review, testing, sizing and context: the other practices around a coding agent. That is the pattern with every one of these practices. A spec is necessary, and on its own it is not enough. Pair it with an independent reviewer, tests that run against its criteria, and a check at the end, and it starts to pay for itself.

We wrote about that wider set of practices in harness engineering for coding agents. Spec-driven development is the part that decides what "correct" means. The rest is what holds the code to it.

Halfcycle runs spec-driven development inside Claude Code or OpenAI Codex, with the layers and the checks already joined up.

It starts above the feature. You are interviewed one decision at a time, and from your answers it writes the product plan, the architecture and the phases. Each feature then gets a spec with acceptance criteria and its boundaries, and the rules that hold across the product are written once and referred to.

Before any code, an agent that did not write the spec reviews it. During the build, tests are written from the criteria and must fail before the code exists and pass after. Each task is reviewed by an agent that did not build it. At the end of the phase the whole goal is checked against the plan, and the delivered product is walked through, so a criterion that was missed shows up as missed rather than as done.

The amount of all this depends on the change. Halfcycle decides how much process a change needs from what it touches, so a small fix takes a short path and a risky change gets the full treatment.

And it gets better at specs over time. When a project implementation goes wrong because a spec missed something, both the cause and the fix are kept and reach every other project automatically. So most of those gaps never open on your project, and the ones that do come with the answer attached. What travels is the shape of the gap, never your code or your documents, and we do not train on anyone's work.

Halfcycle's specs describe the change being built. It does not yet keep one always-current document of how the whole system behaves today; that picture lives in the plan, the architecture and the record of what each phase delivered. It also needs a connection, because the method is served rather than stored in your repository.

And if your change is genuinely small, the right spec may be one sentence. Halfcycle will tell you so. The point of spec-driven development was never paperwork. It is deciding on purpose, before the agent decides for you.

npx halfcycle Enter fullscreen mode Exit fullscreen mode Run that in the folder you want to work in, then open it in Claude Code or OpenAI Codex and say what you are building. Needs Node 20 or newer. There is nothing to learn first, and it tells you what is next when it is next.