Spec-First Prompting: Write a One-Page Design Doc Before You Ask for Code

You can get a lot of code out of an assistant with a single prompt — and you can also get a lot of wrong code. In my experience, the difference usually isn’t model quality. It’s whether you wrote down what you’re actually building. That’s the idea behind Spec-First Prompting : Before you ask for implementation, ask for a one-page spec. It sounds slower. It’s almost always faster. When you skip the spec, you force the assistant to invent requirements, pick defaults you didn’t agree to, and “solve” the wrong problem confidently. When you do the spec, you turn the conversation into something you can test, review, and iterate. Below is a copy/paste template, a concrete example, and a workflow you can reuse. Why spec-first works Most code tasks fail for boring reasons: unclear scope (what’s in vs out ) hidden constraints (runtime, dependencies, security, performance) missing interfaces (CLI flags, function signatures, API endpoints) undefined “done” (how do we know it works?) Assistants are