Write a Spec an Agent Can't Misread

The Build Loop, same as every rung — spec, direct, checkpoint, verify. This rung sharpens the first turn: the spec. And it turns out to be a skill you've been practicing your whole career.

You've written a brief a freelancer couldn't misread. A statement of work that survived contact with a vendor. The pre-kickoff email that kept the meeting from going sideways. Every one of those was a spec — a clear description of what you want, written for someone who has to act on it without you in the room. You already have the muscle. This rung just points it at an agent.

The spec is where the judgment goes now

For as long as software has existed, there was a layer between the person who saw what was needed and the system that built it: you described what you wanted, and someone who spoke code translated it. That translation is now the agent's job — and that does something to the spec you might not expect. It makes it the whole game.

When a person translated your intent, a fuzzy brief got rescued by a dozen hallway conversations. When an agent translates it, the spec is the only conversation there is. Whatever you leave unsaid, the agent decides for you — confidently, plausibly, and sometimes wrong. So the spec stops being the paperwork that comes before the work. It is the work. And it's yours.

The skill you needed is one you already have

Writing a spec an agent builds correctly is not a technical skill. It's the skill of stating a problem so clearly that someone who can't read your mind still gets it right — pattern recognition, compressed into a plain description of what to build. You've used it in every job you've held: the brief, the scope of work, the email that heads off the wrong turn. You just didn't know it counted as engineering. It does now.

Write for a reader who never asks a follow-up

Here's the one real difference between your briefs and the spec an agent needs: your freelancer calls when something's unclear. The agent doesn't. Faced with ambiguity, it does something more dangerous than stopping — it chooses. It picks one of the things you might have meant and builds it beautifully. So the craft isn't writing more; it's closing the specific gaps an agent falls into. Four moves cover most of them.

Lead with intent, not implementation. Say who this is for and what problem it solves before you say a word about how it works. When the agent hits a decision you didn't anticipate — and it will, a dozen times a build — your stated intent is what breaks the tie. A spec without intent is a spec where the ties get broken at random.

Describe what done looks like. Not "add an export feature," but "the user clicks one button and gets a spreadsheet with these five columns — and if there's nothing to export, they're told so instead of getting an empty file." You already do this when you brief creative work. Do it here on purpose.

Name the non-goals. Agents are eager. Say what this build is not: "don't touch the login," "no new screens," "ugly is fine, wrong is not." Every non-goal you write down is an afternoon of unwanted initiative you don't have to unwind later.

Walk one concrete example end to end. "Maria owes forty dollars, uploads her receipt, and sees this." A single worked example settles more ambiguity than three paragraphs of description — because writing it forces you to notice the questions you hadn't answered.

None of these needs technical vocabulary. Every one is a judgment call about your own domain — which is exactly why the agent can't make them for you.

Catch the confident misread before it becomes a build

I'll be honest about where this fails, because it failed for me. I wrote what I thought was a tight spec and got back something polished, competent, and wrong — it solved a neighboring problem, and nothing in it looked broken. That's the failure to burn into memory: an agent that misreads you doesn't hand you garbage. It hands you a fluent answer to a question you didn't ask.

You already know how to catch it. It's what you do when you ask a junior colleague to play an assignment back at the end of a check-in — not to catch them out, but because the playback is where the misunderstanding surfaces while it's still cheap. Do exactly that here. Make the agent restate the plan before it builds. Before you authorize a single change, say: "Restate the plan in your own words — what you're building, what you're not building, and anything you're unsure about." Then read it the way you'd read that junior's recap. A misread caught in the restatement costs you one clarifying sentence. The same misread caught after the build costs you an afternoon — and a little of your faith that your specs work.

That's the rung: you can take an idea out of your head and have it arrive in working software with your judgment intact — not "close enough to fix later," but the thing you actually meant. The people who saw the patterns used to be consulted. Write specs like this, and you're not consulted anymore. You're building.

→ The companion — In Tropo: Your First Spec — hands you a fill-in skeleton (intent, done, non-goals, one worked example), points it at a real feature, and ends on the restate step.

Power Play

Before you hand your spec to the agent that will build it, hand it to a different agent to tear apart first. Give the reviewer this:

"I'm about to give this spec to an agent that will build exactly what it says and can't ask me a single question. Read it the way that agent will. Tell me every place it's ambiguous, every decision I left unmade, and every spot where you'd have to guess — then suggest the wording that would remove the guesswork."

Fix what it finds, then build. You've just run a check-in before the work started — catching the misreads on paper, where they cost nothing, instead of in the build, where they cost your afternoon.

Terms worth knowing

• Spec — a written description of what you want built, clear enough that an agent who can't ask follow-up questions still builds the right thing. In agentic building, the spec is the program.
• Non-goal — something you explicitly tell the agent not to do. The cheapest line in any spec, and the one people forget.
• Plan mode — some agent tools have a setting that forces the agent to propose its plan and get your approval before changing anything. If yours has it, it's the restate tactic with a seatbelt. If not, asking for the restatement in plain words works everywhere.