Most bad agent results start with a prompt that describes a wish instead of a task. "Make the checkout faster" is a wish. The agent has to guess what faster means, where to look, what it may change and when to stop. Every guess is a chance to go wrong.
An actionable prompt removes the guesses. It has five parts.
The five parts
| Part | Question it answers | Example |
|---|---|---|
| Goal | What outcome do you want? | "Cut p95 latency of POST /checkout below 300 ms." |
| Context | What does the agent need to know that it cannot see? | "Profiling shows 70% of time in price_cart(). Prices change daily." |
| Constraints | What must it do or avoid? | "No new dependencies. Keep the public API unchanged." |
| Output | What should it hand back? | "A diff plus a 5-line explanation." |
| Done when | How will you both know it worked? | "pytest tests/checkout passes and the benchmark script shows < 300 ms." |
You will not need all five every time. A one-line fix needs a goal and maybe a done-when. But when a result disappoints, the missing part is usually one of these.
Before and after
Before:
Make the checkout faster.After:
Goal: cut p95 latency of POST /checkout below 300 ms (currently ~800 ms).
Context: profiling (attached) shows ~70% of time in price_cart() in
src/billing/pricing.py. Prices change once a day.
Constraints: no new dependencies; keep the function signatures; do not
touch the payment client.
Output: a diff and a short explanation of the change and its risks.
Done when: pytest tests/checkout passes and scripts/bench_checkout.py
reports p95 < 300 ms.The second prompt is longer, but it saves the agent from reading the whole billing package, stops it adding Redis "to be safe", and gives it a way to check its own work.
Write the goal as an outcome
Compare:
- "Refactor the auth module." (activity)
- "Make it possible to add a new OAuth provider by adding one file." (outcome)
The outcome tells the agent which refactor you want, and gives you a test: can you add a provider with one file?
Done-when is the most underused part
Agents that can run commands can check themselves, if you tell them how. A done-when line turns "I think this works" into "I ran the tests and they pass".
Good done-when checks are:
- Runnable: a command, a script, a URL to load.
- Specific: "returns 200 with a JSON body containing
id", not "works". - Cheap: seconds, not an hour-long suite, so the agent actually runs them.
Step by step: rewrite one of your prompts
- Open your last three agent chats and pick the one that needed the most follow-ups.
- Copy your first message into a scratch file.
- Under it, write the five headings: Goal, Context, Constraints, Output, Done when.
- Fill each heading using what you had to explain in the follow-ups.
- Next time a similar task comes up, start with the filled version and count the follow-ups again.
Common mistakes
- Hiding the goal in the middle. Put it first. Models weigh the start of a message heavily.
- Constraints as suggestions. "Try not to add dependencies" invites one. "No new dependencies" does not.
- Asking for everything. "Fix it, add tests, update docs, and refactor" produces a shallow version of each. Split it.
Quick check
-
Which part lets an agent verify its own work?Done when: a runnable, specific, cheap check.
-
Rewrite "Clean up the logging" as an outcome.For example: "Every log line in src/api uses the shared logger with a request_id field, and no print() calls remain."
-
When can you skip most of the five parts?For small, unambiguous tasks such as a one-line fix with an obvious test.






