A Spec Before a Prompt

Every AI-assisted build I ship starts with a spec, not a prompt, and that’s the part most people skip.

The temptation is the same every time. Open the tool, describe roughly what you want, and let it run. I’ve felt it on the site I built for my HVAC client, on my own marketing report, and on the workflow behind my LinkedIn posts. It’s a good feeling, because something appears on the screen within minutes.

Where prompting alone breaks

Describing what you want and letting the model run works fine for a demo. It falls apart the moment something has to work correctly every week. A demo only has to look right once, in front of you. A weekly report has to be right on the fourteenth Monday, after a data source changed its format and nobody remembered what the report was supposed to do in the first place.

The failure isn’t dramatic. It’s a model filling in blanks you didn’t know you’d left, with reasonable guesses that happen to be wrong for your business. You find out later, usually from a number that looks off, and by then you’re untangling decisions that were never written down.

What the spec forces

The framework I use is GSD, short for Get Shit Done. Before Claude Code touches a single file, it makes me write out the phases, the requirements, and the edge cases. What gets built first, what depends on what, and what “done” means for each piece.

That last one is the real work. When I write down what done looks like, I find the gaps in my own thinking while they’re still cheap to fix, not after the model has built three screens on top of them.

It’s slower for the first twenty minutes and faster for every hour after.

That’s the trade, and I’d make it again. The model isn’t guessing what done means, and I’m not re-explaining the same context three prompts in. Each phase starts from a written reference instead of my memory of what I said earlier, which matters more than it sounds once a project runs longer than one sitting.

Where the horror stories come from

Most of the AI horror stories I hear from other builders aren’t really about the model being bad. They’re about someone skipping the thinking step and asking the tool to do it for them. The tool did what it was asked, and what it was asked was vague.

A model writes code quickly and has no way of knowing what your business needs unless you’ve said so. Saying so in writing, before anything gets built, is the part I can’t hand off.

It’s the same habit I bring to client work. A marketing system someone depends on every week gets a written definition of what it’s supposed to do, and that definition is the first thing I produce.

What’s your process for scoping a build before you touch the AI tool, or do you skip straight to prompting?