Writing agent-ready prompts

Most bad results from an AI coding agent trace back to the prompt, not the model. I’ve watched this fail the same handful of ways enough times to write them down instead of relitigating them every time someone on my team hits one.

The single biggest fix is naming the file or files you expect to be touched. “Fix the checkout bug” sends the agent hunting through your whole codebase for anything checkout-shaped, and it’ll often find something plausible-looking that isn’t the actual bug. “The discount code field in src/components/CheckoutForm.tsx doesn’t validate before submit, it should reject codes under 4 characters” gives it a starting point and a stopping point in the same sentence. You don’t need to know the fix, just the location and the symptom.

Symptom over solution matters too. If you already know the fix, just say it. But if you don’t, describe what’s actually happening rather than guessing at a cause — “the modal closes immediately after opening” is more useful than “there’s a race condition in the modal,” because the second one is your theory, and if it’s wrong, you’ve steered the agent toward debugging the wrong thing. Let it find the cause; you supply the observed behavior.

Scope is the other big one. Open-ended prompts like “clean this up” or “make this more efficient” don’t have a natural stopping point, so the agent has to guess how far to go, and it’ll guess wrong in one direction or the other about half the time. Either too timid to be useful or too aggressive and touching things you didn’t want touched. Give it a boundary: “reduce the re-renders in this component, don’t touch the API calls” tells it both what to optimize and what not to.

Context you assume is obvious usually isn’t. If your team has a convention — all API calls go through a shared client, all dates are stored as UTC, tests live next to the file they test rather than in a separate directory — the agent doesn’t know that until you say it or until it infers it from reading enough of the codebase. For a one-off task, stating the convention up front is faster than hoping it gets inferred correctly.

Two other things worth doing habitually: ask for a plan before execution on anything that touches more than one file, so you can catch a wrong assumption before it becomes a diff. And when a result comes back wrong, don’t just say “that’s wrong, try again” — say what specifically is wrong and what you expected instead. Vague correction prompts tend to produce a second attempt that’s differently wrong rather than more correct, because the agent doesn’t actually know what it got wrong the first time.

None of this is exotic. It’s the same discipline you’d want from a ticket written for a junior developer who’s never seen your codebase before, because functionally, that’s what you’re writing for.