Spec first. Or why AI feels random until it doesn't

Quick note: this one is for developers. If you're here mostly for PlayPhrase.me updates, feel free to skip it - there's nothing new in the product today. This is about how things get built behind the scenes.

I was at a dev conference recently, and one thing kept bothering me afterward.

A lot of people still don't really know how to work with AI in development. Not at the level of "which agent should I use," but at a much more basic level.

They still start without a spec.

They jump straight into code. Or straight into a chat with AI. And then the same cycle starts:

"It doesn't work."

"The logic drifted."

"Let's rewrite it again."

You see this on X all the time. People blame the model, compare agents, complain that one tool produced one result and another produced something else.

Most of the time, that's not the real problem.

The real problem is that people give AI a half-formed thought and expect reliable execution.

If there is no specification, AI is not executing a task. It is filling in gaps.

It has to guess what "correct behavior" means, which cases matter, where the boundaries are, which contracts cannot break, and what to do with edge cases. If none of that is defined, unstable output is the expected outcome.

You didn't give it a task. You gave it clues.

For a while now, I've been working differently.

First we talk through the idea.

Then we define behavior, scenarios, and contracts.

Then we turn that into a spec.

Only after that do we write code.

Once that part is done, the coding becomes almost mechanical. Not because AI suddenly became perfect. Because the worst kind of chaos disappears: the developer, the model, and the system are no longer guessing what is being built.

That alone means fewer surprises, fewer rewrites, and fewer "quick fixes" that quietly eat half a day.

The funny part is that switching to this was trivial. I just pulled my basic setup into a small repo:

https://github.com/potapenko/spec-first-bootstrap

Drop it into a project, and agents like Codex or Claude stop rushing into code immediately. They start with the spec, refine behavior, and only then write code.

Which is how development was supposed to work in the first place.

At some point, people decided AI would magically remove the specification step.

It doesn't.

If I had to boil it down to one point, it's this:

The main skill is no longer writing code.

The main skill is defining, precisely, what should be built.

Get that right, and AI speeds you up.

Skip it, and it just amplifies the chaos.

And if the repo looks useful, stars are welcome.