What to hand your coding agent instead of a prompt

Two people open the same agent, on the same model, and ask for the same product. One gets something shippable. One gets a demo that falls apart on the second screen. The gap is almost never the model.

Agents are not bad at building. They are bad at guessing.

Modern coding agents will happily produce thousands of lines of working code from a sentence. That is the problem. Nothing fails loudly. You do not get an error saying "you never told me who this is for", you get a confident implementation of a product nobody asked for, and you find out three screens in.

Every gap in your brief becomes a silent decision. Not a question. A decision, made once, propagated everywhere, and expensive to reverse by the time you notice.

The four things worth writing down

1. A fixed target, not a description

There is a difference between telling an agent about your idea and giving it something to build against. A description is prose you retype slightly differently every session. A target is a document that does not change between sessions, which means the build does not either.

This is the single highest leverage change. It converts your agent from a collaborator who needs reminding into one that can resume.

2. The constraints you have already settled

Stack, versions, platform, and the things that are explicitly out of scope. "React 19 with TypeScript and Vite, no CSS framework, no auth in phase one" removes four decisions the model would otherwise make on your behalf, differently each time.

Out of scope is the half people forget. An agent with no stated boundary will keep helpfully adding surface area, and every addition is more code you now own.

3. The why behind each feature

A feature described only by its mechanics gets built to the letter and misses the point. A one line user story in the user's own voice fixes this cheaply, because it gives the model something to check its implementation against.

"Users can filter results" produces a filter. "As someone browsing on my phone during a commute, I want to narrow this to the three that matter so I am not scrolling for ten minutes" produces a different filter, and the second one is right.

4. What done looks like

Acceptance criteria turn an open ended build into something the agent can verify itself against. Without them, "done" means the model ran out of obvious things to add, which is not the same thing at all.

Where the brief should live

Not in the chat. Context windows end, sessions get cleared, and the agent you talk to tomorrow has no memory of the forty small corrections you made today. Anything important that exists only in a conversation is already lost.

Anything you would have to explain twice belongs in a file the agent can read, or a tool it can call.

That is what the tool layer is for. Rather than pasting a document into the window and hoping it survives the session, the agent fetches it when it needs it:

> Use idz mcp to fetch my latest specification and build the idea

  idz - get_your_ideas (MCP)(searchText: "AI Guitar Tabs")
  idz - get_idea_specifications (MCP)(uuid: "88e4b702-...")
  idz - build_idea (MCP)(uuid: "88e4b702-...", specificationId: "9")

  Ready. 3 phases, 12 tasks.

Same brief, every session, on any machine, with any client that speaks MCP. Setting that up takes one command.

Do not confuse a longer prompt with a better one

The instinct after a bad build is to write more words. It helps a little, then stops helping, because you are still describing rather than specifying, and a wall of prose has no structure the model can navigate.

Structure is what makes a brief useful: named sections, features split into what ships first and what waits, entities and relationships written down once. A schema also makes its own gaps visible. An empty acceptance criteria list is obviously empty. A rambling paragraph that forgot to mention testing is not.

Hand your agent a specification instead of a vague prompt.

Where the content comes from

A brief you wrote alone is still your assumptions, formatted nicely. It will be internally consistent and possibly wrong. The version that holds up is the one built from what other people told you: the feature requests you would not have thought of, the objections that killed a screen before you built it, and some measure of who actually wants this beyond politeness.

That is the part worth doing before you open the editor, not after.