A prompt to a coding agent is a specification, even when it sounds like a conversation. The quality of the result depends on how much of the specification you state and how much the agent has to guess. Most bad output comes from guesses the author did not know they had left open.
The four parts of a good prompt
1. One goal. "Add a product list page" is a goal. "Improve the shop" is a wish. Split large wishes into goals the agent can finish and check.
2. The files it may change. "Edit only src/pages/Products.tsx and its test" stops the agent from rewriting the app. Naming files also makes review faster.
3. What to leave alone. "Do not change the API shape or the routing" prevents quiet breakage. Agents are good at tidying things you did not ask them to touch.
4. A check it can run. "Run the tests and report what passed" turns a guess into a result you can read. The agent should report the output, not a summary of what it believes happened.
An example
Weak: "Make the orders page better."
Better:
Add a filter to the orders page that shows only unshipped orders.
Edit onlysrc/pages/Orders.tsxand its test file.
Use the existingfetchOrdersfunction. Do not change its signature.
Keep the current table layout.
Run the tests and report the output.
The second version can be checked in a minute. The first can take an hour and still miss the point.
Common mistakes
- Asking for "best practices" without naming them. The agent will choose its own, which may not match your project.
- Hiding the constraint in a long paragraph. Put limits in a short list the agent can scan.
- Accepting a summary instead of output. Ask for the test output, the build log, or the diff.
- Asking the agent to judge its own work alone. Give it a check that does not depend on its opinion.
When to stop and ask
A good prompt tells the agent to stop when it is unsure. "If the API response shape is unclear, stop and ask instead of guessing" prevents a confident error that costs more to find than the question would have.
Keep a prompt library
When a prompt works well, save it with the project. Teams that reuse tested prompts get more consistent results than teams that retype a new prompt each time.
Summary
Write prompts as small specifications: one goal, named files, explicit limits, a check to run, and a rule for stopping. The more of the work you specify, the less the agent has to guess, and the less you have to review.
