AI coding agents guess when your spec is vague: a one-page template that stops it

A good spec for an AI coding agent is one page, written in plain language, that says what the user can do, what "done" looks like, and what the agent must not touch. It is less like a product vision document and more like a work order.

The reason is simple. A human developer who gets a vague spec will usually come back with questions. An AI coding agent (software like Claude Code that reads your instructions and writes the code itself) will usually just start building. It fills every gap with a guess, and it does so confidently. You find out which guesses were wrong when you open the product.

So the spec has one job: remove the gaps before the agent gets to them. Here is how I do it, and the template I use.

Why agents need different specs than people

Three differences matter.

First, agents don't push back. A person will say "you said users can upload a file, but what file types?" An agent picks a file type and moves on.

Second, agents don't remember. Each session starts close to blank, so anything not written down does not exist. The spec is the memory.

Third, agents are good at checking their own work against something concrete. If you give them a testable statement, such as "a user who enters a wrong password sees an error and stays on the login page," they can build it and verify it. If you give them "login should feel smooth," they can do nothing with it.

I build MVPs with Claude Code on Cloudflare daily, and this is the pattern that keeps showing up. The vaguer the instruction, the more I spend later undoing decisions I never made.

The one-page spec template

Copy this and fill in each part. If a section takes more than a few lines, the task is too big. Split it into two specs.

Goal (one sentence). What the user can do after this is built that they cannot do now. Example shape: "A customer can book a 30-minute call from the pricing page."
Who it's for. The specific user, and what they know. "A first-time visitor, not logged in" changes the build.
Behavior, as plain statements. A short list of "when the user does X, the product does Y." Include at least one failure case: what happens when something goes wrong, like a payment that fails or an empty form.
Done means. Three to five checks anyone could run by hand. These double as the agent's tests and as your acceptance review.
Out of scope. What the agent must not build or change. This is the most skipped section and the most valuable. "Do not change the sign-up flow. Do not add new tools or services."
Existing things to respect. Which parts of the product already work and must keep working, and any rules already decided (the brand name, the database you use, the pages that exist).
Open questions. Anything you have not decided. Tell the agent to stop and ask rather than guess on these.

That is the whole template. Seven short sections, one page.

What good and bad lines look like

The difference is whether a stranger could check it.

Bad: "Make onboarding easy." Good: "A new user reaches the dashboard in three screens or fewer."
Bad: "Handle errors well." Good: "If the payment fails, show the message 'Payment didn't go through' and keep the cart."
Bad: "Support teams." Good: "An account has one owner and up to five members. Members cannot delete the account."

If you cannot write the good version, that is useful information. It means you have not decided yet, and the right place for that line is "Open questions."

Common mistakes

Writing a vision instead of a task. "An all-in-one platform for property managers" gives an agent nothing to build. One feature per spec.
Skipping "out of scope." Agents are helpful to a fault. Without a boundary, they will tidy, refactor, and add things you did not ask for.
Describing the screens but not the rules. The look is the easy part. The rules (who can see what, what happens at the limit, what happens on failure) are where products break.
Bundling five features into one spec. Long, mixed requests produce work that is hard to review. Small specs give you small, checkable results.
Never reading the result against the spec. The "Done means" list exists so you can run it yourself. If you cannot, ask for a short walkthrough of how to test each point.

What has changed recently

Agents are getting better at working through longer tasks on their own, which makes the spec matter more, not less. The more room an agent has to run, the further a wrong assumption travels before anyone sees it. A tight spec is how you keep that independence pointed in the right direction.

It also helps after the build. A spec with clear "done" checks gives you a way to review what came back. When you are ready to judge whether the result is safe to put in front of real users, my production-readiness checklist for AI-built apps picks up where the spec leaves off.

What to do this week

Pick the next feature you want built. Before you hand it to anyone, human or agent, fill in the seven sections above. Time yourself. If it takes more than 30 minutes, the feature is too big, so cut it in half.

Then look at your "Open questions" list. Those are the decisions that only you can make, and they are the ones an agent would otherwise have made for you. Answer them first.