OpenSpec Optimizes Chaos, Not Tokens

I had OpenSpec in the wrong category for a while.

I was evaluating it the way I evaluated everything else in my AI stack: does it reduce token usage? Does it improve retrieval? Does it make the agent smarter?

None of those are the right question for OpenSpec.

What I was trying to solve

The problem I kept running into was agents that started too fast.

The task would be something like: implement this new endpoint, wire it to the service layer, add the necessary auth checks.

Reasonable task. Clear enough intention. And the agent would start immediately.

Thirty minutes later, things would start fraying. The API contract was implicit. The data model was decided mid-implementation. The auth logic was added as an afterthought. Two different files made the same assumption in two different ways, and neither assumption was right.

I had not given the agent a chaotic task. I had given it a reasonable one. But without structure, even reasonable tasks generate chaotic execution.

That was the pressure.

The category error I was making

I was treating all the useful layers in my AI stack as if they solved the same kind of problem.

They do not.

Some layers give the agent knowledge: what does this library do, how does this API work, what are the current conventions.

Some layers give the agent capability: inspect the running app, access a component system, introspect runtime state.

OpenSpec is neither of those.

OpenSpec is about making work coherent before it starts.

Once I put it in that category, everything about it made more sense.

What OpenSpec actually does

The discipline is simple: no implementation before a proposal exists.

Before the agent writes a line of code, it writes a spec:

• what is being built and why
• what the API contract looks like
• where data lives and how it flows
• what assumptions are being made explicit

That spec then becomes the thing that gets reviewed, not the code.

The difference matters. A design mistake caught in a ten-line spec costs almost nothing. The same mistake caught after implementation costs hours of rework, and usually leaves behind residue in the codebase.

Why "chaos" is the right word

The optimization is not token-based. It is structural.

Better retrieval does not fix unstructured work. More documentation does not help if the work plan itself is incoherent. A smarter model still executes faster into the wrong direction if there is no checkpoint before execution.

Chaos in AI-assisted development looks specific:

• multiple implicit decisions made during implementation instead of before
• design choices that are hard to reverse once code exists
• inconsistent assumptions across files that all looked fine in isolation
• effort spent on implementation that turns out to be wrong at the architecture level

OpenSpec creates one forcing function: make the decision visible before it gets embedded in code.

That is the constraint it addresses.

The cost is real but small

Spec-driven development is overhead on trivial tasks. I am not writing a formal document every time I change a variable name.

But once a task involves more than one decision, more than one boundary, more than one person or session, the spec pays for itself quickly.

The forcing function it creates is useful even when I am the only one reviewing it. Writing the spec surfaces assumptions I was about to make silently. Reviewing it before starting catches direction problems that would have been expensive to find halfway through.

What this changed in practice

I now use OpenSpec proportionally.

Simple, well-understood changes: no spec, or a single-line note. Complex features, cross-boundary work, anything touching authorization or tenant scope: a real spec before any implementation.

The result is not slower development. It is development where the waste is front-loaded into thinking instead of back-loaded into rework.

And when the spec is wrong, that is fine. Wrong in writing is cheap. Wrong in code is not.