Write the Spec Before the Prompt, Every Time

Write the spec before the prompt. Not after, not instead of, before. The prompt is where you ask the model to build. The spec is where you decide what building even means. If you skip the spec and go straight to the prompt, the model decides for you, and it decides badly because it fills gaps with the average of everything it has seen.

I build this way across every company I run. The rule is simple: no prompt touches a real codebase until there is a spec it can be checked against.

Why write the spec first at all?

Because a spec is the cheapest artifact you will ever produce. It is words. You can throw it away, rewrite it, argue with it, and it costs you nothing but a few minutes. Generated code is not cheap in the same way. The moment code exists, other code starts depending on it, and every change gets more expensive.

So you want to be wrong in the spec, where wrong is free, not in the code, where wrong compounds. The spec is your sandbox for bad ideas. Use it hard. List the routes. List the data shapes. List the states the thing can be in. Write down what it must not do. By the time you prompt, the hard thinking is done and the model is just typing.

What goes in the spec and what does not?

The spec holds decisions. Not prose, not justification, decisions.

Put in: the exact entities and their fields, the API surface, the user-visible states, the edge cases you already know will bite, the definition of done. Anything the model would otherwise guess at, you put in the spec so it does not have to guess.

Leave out: implementation detail the model is genuinely good at. You do not need to specify how to write a loop. You need to specify what the loop is for. Over-specifying wastes the model's real strength, which is turning clear intent into working code. Under-specifying gives it too much room to invent. The spec lives in that middle band: fully decided on intent, loose on mechanics.

I went deeper on the practice itself in spec-driven development. This post is narrower. It is about the ordering. Spec, then prompt. That sequence is the whole point.

Does not the model just figure it out?

It figures out something. That is the problem. Ask a model to "add billing" with no spec and it will add billing. It will pick a schema, pick a provider abstraction, pick where the logic lives. All plausible, none yours. Now you own a subsystem you did not design, and the next feature has to route around decisions you never made on purpose.

This is how AI-generated code turns into a mess. Not because the code is bad line by line. Because nobody decided the shape, so the shape is whatever the model averaged into existence. The spec is how you take that decision back. It is the difference between the model working for your architecture and your architecture bending around the model.

When is the spec allowed to change?

Often. Specs are not contracts you sign in blood. When you generate against a spec and reality pushes back, you update the spec and re-run. That is not failure, that is the loop working. The spec is a living plan, and the build loop exists to keep the spec and the code in agreement.

What you never do is let the code drift ahead of the spec silently. If the code does something the spec does not describe, one of them is wrong, and you fix it before you move on. Drift is the thing that kills AI-assisted projects. The spec is your instrument for catching it early.

Doing this at speed

The objection is always the same: writing specs first is slower. It is slower for the first ten minutes and faster for everything after. I ship faster with specs than I ever did without them, because the generate step almost never surprises me. The surprises got moved up front, into cheap words, where I could deal with them for free.

I run this inside Bootspring, where the spec is a first-class object the build loop reads from, not a doc that rots in a folder. When the spec and the generator share one system, writing the spec first stops being a chore and starts being the fastest path to working software. The tool for scoring what actually came out, I keep separate at ReformCode, because verifying the result is its own job.

Spec first. Prompt second. Every time. The order is not a preference. It is where the speed comes from.