Specs beat instructions: a quiet shift in how we work with AI.

A pattern I have been watching across teams using AI coding assistants: the people who consistently get good output are not the ones writing clever prompts. They are the ones who have quietly stopped writing prompts altogether.

What they write instead are specs.

The difference, in one example

Here is an instruction:

Add a rate limiter to our login endpoint so users cannot spam it.

Here is a spec for the same thing:

Add a rate limiter to the login endpoint. Limit: 5 attempts per email per 10 minutes. On exceed, return 429 with the standard Retry-After header. Counter resets on successful login. Failed attempts from different IPs against the same email all count toward the same bucket. Bucket storage is in-memory for now; we will move it to a shared store when we scale horizontally.

Same feature. Same outcome. The instruction takes ten seconds to write and produces a response that requires three rounds of clarification before the code is usable. The spec takes two minutes to write and produces working code on the first attempt.

Why specs work and instructions do not

Modern AI assistants are extraordinarily good at filling in the gaps in what you tell them. That sounds like a feature. It is mostly a trap.

When you give an instruction, the model fills the gaps with plausible defaults drawn from training data. Those defaults are statistically likely but rarely match what you actually wanted. You then spend the next twenty minutes correcting them.

When you give a spec, you are removing the model's need to guess. Every decision the model would have hallucinated is now in front of it as input. The output is closer to a translation than a creation, and translations are something these models are quietly excellent at.

The five things a good spec answers

Over the last few months I have noticed that the specs that work best tend to answer the same five questions, more or less in this order:

1. What is the desired end state? Not "add a feature" — describe the behaviour after the change is in place.
2. What are the inputs and the contract? Types, shapes, edge cases, null behaviour. Boring but load-bearing.
3. What are the failure modes? What happens when something goes wrong, and which of those failures are recoverable.
4. What is explicitly out of scope? The fastest way to a clean output is to tell the model what not to do.
5. What does "done" look like? A test, a curl command, a screenshot expectation. Something the model can self-check against.

If your spec answers all five, you usually get working code in one shot. If it answers three, you get something close that needs editing. If it answers one, you get a conversation.

The objection: "this is just writing more"

The first reaction most engineers have when they hear this is that it sounds like extra work. Writing a spec takes longer than writing a prompt. True, on the input side.

But here is what is harder to see: the time you spend writing a spec is time you were going to spend anyway, just spread across the next thirty minutes of back-and-forth correction. Front-loading that thinking is not extra work; it is the same work, compressed.

The choice is not between writing a spec and not writing one. It is between writing a spec before the model starts, or writing one inside out by correcting drafts.

What this means for the role

There is a broader implication here that we are only starting to understand. The valuable skill is shifting away from "knowing how to code" and toward "knowing how to specify what you want." The first half of that has always mattered; the second half used to be optional. It no longer is.

The engineers who will thrive in the next few years are not the ones who can write code the fastest. They are the ones who can describe a system precisely enough that a model, an intern, or their future selves can build it without ambiguity.

That is a skill. It is teachable. And, as far as I can tell, it is the single highest leverage thing to be working on right now.