Writing Prompts AI Coding Agents Actually Understand

Why this is a different problem from a vague Google search

A vague search engine query gets you a list of results to judge and pick from yourself, no real cost to trying again with better words. A vague prompt to an AI coding agent isn't a query, it's an instruction the agent acts on directly, changing real files in your actual project. When the wording is ambiguous, the agent doesn't hand you a list of interpretations to choose from, it picks one and commits to it. If that guess is wrong, you don't get a bad search result, you get an actual, live change to your app that you now have to notice, diagnose and undo.

This is also why the same habits that work fine when talking to a person don't transfer cleanly. A colleague hearing "fix the contact form" asks a clarifying question before touching anything, since asking costs almost nothing and getting it wrong costs their afternoon. An AI coding agent is built to act quickly on what you give it rather than pause and interview you first, so the clarifying question you'd normally get from a person has to be baked into the prompt itself, upfront, or it doesn't happen at all.

The three things a well-formed prompt always includes

Where: name the specific page, component or feature involved, as precisely as you can describe it, not the whole app in general terms. What: describe the exact behaviour you want, not just that something is "wrong" or "better." What shouldn't change: say explicitly what needs to stay exactly as it is, especially anything nearby that an agent might reasonably assume is fair game to touch while it's in that part of the code.

None of these need technical language to work. "The contact form on the homepage should show an error message under the email field if it's left blank, and shouldn't change anything else on that page" names all three without a single technical term, and gives an agent far less room to guess than "fix the contact form."

Describe the symptom, not your guess at the cause

A common way a well-intentioned prompt still goes wrong: describing what you think is broken instead of what you're actually seeing. "The API key must be wrong" sends the agent looking in exactly the wrong place if the real problem is something else entirely, a mismatched field name, a missing permission, a totally different cause you haven't considered. "Submitting the form does nothing and the browser console shows a 403 error" describes the actual symptom and lets the agent diagnose the real cause itself, which it's usually better positioned to do than you are from the outside.

Iterate on the prompt, not the output

When a result isn't right, the instinct is often to start manually editing what the agent produced. On a platform built around prompting, refining the prompt itself and generating again is usually the faster, more reliable path; these platforms are built for fast prompt-to-result cycles, not for hand-editing generated code piece by piece. Treat a wrong result as a signal your prompt was missing one of the three things above, and fix the prompt, not the output.

A follow-up prompt needs the same three-part discipline as a first one, not less of it. "That's still not right" tells the agent almost nothing new to work from, and often produces a different wrong guess rather than a correction toward the right one. A useful follow-up names what changed since the last attempt and what's still wrong specifically, and repeats the boundary about what shouldn't move, the same structure as the original prompt, applied again rather than assumed to still be understood.

Where you have one, a concrete example helps more than another sentence of description. Pointing at a specific existing page on your own site ("match the spacing this section already uses") or describing a reference you've seen elsewhere gives the agent something to match against, rather than asking it to interpret an adjective like "cleaner" or "more modern" entirely on its own judgement.