Writing specs an agent can actually build from

Ask an engineer what went wrong with their last agent session and you'll usually hear some version of "it built the wrong thing, confidently." The instinct is to blame the model, or to go hunting for a cleverer prompt. But watch the sessions that go *well* and the pattern is almost boring: the people getting great output aren't prompting better. They're specifying better. When implementation is nearly free, the description of the work becomes the work — and most of us have spent our careers letting that muscle stay soft, because the code was always there to absorb the ambiguity.

The spec was always the job. Now it's visible.

Before agents, a vague ticket got repaired invisibly. You picked it up, noticed the gaps, filled them with context you carried in your head, and the spec's flaws never showed because a human interpreter stood between the words and the software. An agent is a much more literal reader. It fills gaps too — but with plausible defaults instead of your context, and at a speed that means a thousand lines of the wrong thing before your coffee cools. The ambiguity was always there. The agent just invoices you for it.

This is why "prompt engineering" advice ages so badly. Phrasing tricks target the model's quirks, which change with every release. Specification discipline targets the *problem's* structure, which doesn't. A spec that would let a competent contractor build the right thing on the first try will steer any decent model — this year's and next year's.

The anatomy of a buildable spec

A working spec for an agent-sized task fits on one page and answers four questions. Before you hand over anything non-trivial, check that all four are on it:

• Context and constraints. Where this lives in the system, what it must not touch, which conventions apply. The stuff a new teammate would absorb in onboarding — the agent gets it here or invents it.
• Behavior, with real examples. Not "parse the dates" but "given `03/04/2025` from a EU-locale account, produce April 3rd." Two or three concrete input→output pairs, including one ugly edge case, outperform paragraphs of description.
• Non-goals. The adjacent problems you are deliberately not solving. This is the section that prevents the agent's favorite failure: helpfully expanding scope until the diff is unreviewable.
• Acceptance checks. How you'll decide it's done — the commands you'll run, the cases that must pass, the behavior you'll verify by hand.

Write the acceptance checks first

Of the four sections, the last one carries the most weight, and it's worth writing *first*. Deciding how you'll verify the work forces the fuzzy parts into the open before the agent meets them. If you can't describe the check, you don't yet know what you're asking for — and it's far cheaper to discover that in a text file than in a two-thousand-line diff.

There's a compounding benefit: acceptance checks convert directly into tests, and a spec with testable claims turns the agent loop from "generate and hope" into "generate and verify." You stop reviewing for *what is this?* and start reviewing for *does it satisfy the contract?* — a dramatically easier question to answer at speed.

Say what you don't want

Human specs skip non-goals because humans share defaults — no teammate needs to be told not to introduce a new framework to format a date. Agents genuinely need the fence. "Do not add dependencies. Do not modify the schema. Prefer the existing retry helper over writing a new one" reads like micromanagement and works like magic. Every explicit non-goal is a category of rework you just declined to pay for.

Keep a running list. Every time an agent surprises you — the unnecessary abstraction, the drive-by refactor, the config option nobody asked for — that surprise is a non-goal for your next spec. Within a month you'll have a personal preamble that eliminates most of your recurring corrections, which is a compounding return no prompt trick offers.

A one-week drill

Take the next five tasks you'd normally start with an improvised prompt and spend ten minutes writing the one-pager first: context, examples, non-goals, acceptance checks. Then hand it over and keep score — how often the first result was accepted, how many correction rounds you skipped, how the review felt. Most engineers find the ten minutes pays for itself before lunch, and the discipline quietly upgrades their tickets, their design docs, and their delegation to humans too.

That's the quiet career story inside this skill. Specification has always been what senior engineers were actually paid for — the code was just the proof. The agents didn't change that. They stripped away everything that was hiding it.