Write the Spec First. Everything Else Gets Easier.

For years I treated specs as busywork. Then AI agents started writing my code, and the spec quietly became the whole job.

I used to think specs were for people who didn’t like to code.

You write a long document, everyone nods in a meeting, and then the code goes off and does its own thing anyway. So why bother? Just build it, ship it, fix it later.

I don’t think that anymore. And the thing that changed my mind wasn’t a process book. It was watching AI agents write code for me.

The problem was never the code

Here’s what I kept seeing, for years, across teams.

A developer picks up a task. The task says “add refunds.” They build refunds. It works. Then review starts, and someone asks: what happens on a partial refund? What if the payment already settled? What about a refund on a refund?

None of that was in the task. So now we’re redesigning in the review, which is the most expensive place to design anything.

The code was fine. The problem was that nobody agreed on what “add refunds” actually meant before the code got written. The idea lived in someone’s head, half in a Slack thread, half in a ticket title. Everyone filled the gaps with their own guess.

What a spec really is

A spec is not a 40-page document. It’s the answer to one question: what does “done” look like, before we start?

For refunds, that’s a few plain lines. Full and partial refunds are allowed. A refund can’t exceed the original amount. You can’t refund a payment that hasn’t settled. Every refund needs a reason code. Here are the three states it can be in.

That’s it. Ten minutes of writing. But now the guesswork is gone. The developer isn’t inventing the rules while coding. The reviewer isn’t discovering them during review. QA isn’t finding them in production.

You moved the thinking to the front, where it’s cheap.

Then AI showed up and made it obvious

For a while, spec-driven work was a nice-to-have. A discipline. Some teams did it, most didn’t, and you could get by either way.

AI removed the “get by” option.

When you hand a task to an AI agent, it will write code. Fast. It will fill every gap you left with a confident guess. If your instruction is vague, you don’t get a slower result. You get a wrong result that looks finished.

So the quality of what the agent builds depends almost entirely on the quality of what you told it. A sharp spec in, sharp code out. A fuzzy idea in, a fuzzy mess out, delivered at high speed.

The spec became the actual work. The typing is now the cheap part.

I built an open-source project around exactly this idea. The spec is the source of truth, and the agents build against it. Every time I tried to skip the spec and just “tell it what I want,” I got the same lesson back: the machine only knows what you wrote down.

How I write specs now

I keep it small on purpose. A good spec fits on one screen.

I write what it should do, not how to build it. The “how” is the developer’s job, human or machine. The spec sets the boundary, then gets out of the way.

I write the edge cases down first, because that’s where all the pain hides. The happy path is easy. The refund-on-a-refund is where projects go sideways.

And I write it in plain words. If a spec needs a glossary, it’s not a spec, it’s a hiding place.

The part people miss

Writing the spec first feels slower. It isn’t.

The time you “save” by skipping it doesn’t disappear. It moves. It shows up later as a confused review, a rewrite, a production bug, a support ticket. Same cost, worse timing, and now three more people are involved.

Ten minutes at the start buys back hours at the end. That trade was always worth it. AI just made it impossible to ignore.

So write the spec first. Then let the humans, and the machines, build against something real.

What’s the last thing you shipped that would have been simpler if you’d written down what “done” meant before you started?