Writing a Task the Agent Can Succeed At

Brief it like a capable new colleague

A good task description has five parts: the goal and why ("orders API is slow for big customers; add cursor pagination"), where to look (files, similar existing code), constraints (no new dependencies, keep the response format backward compatible, performance limits), how to verify (the commands that must pass, or the tests to write first) and the scope ("only the orders endpoint; do not refactor"). Vague tasks ("improve the code") produce large, unfocused diffs; over-prescriptive ones ("on line 42 change x to y") waste the agent's ability and risk wrong detail. For ambiguous requirements, ask the agent to propose a plan or ask questions first and approve it before it edits. Include examples of desired behaviour and edge cases; they double as tests.

Plan, test, small steps, parallel

The best results come from clear goals, tests as the target, small reviewable changes and, when useful, several agents in isolated branches.

A weak and a strong task

Same intent; the second gives the agent what it needs to succeed and be checked.

WEAK
  Make the cart code better.

STRONG
  Goal: Cart.total() wrongly applies discounts (apply_discount divides the percent by 10).
  Look at: shop/pricing.py, tests/test_pricing.py.
  Constraints: keep the function signatures; no new dependencies; money stays a float for now.
  Verify: `python -m unittest discover -s tests -t .` must pass; add a test for 15% off 200.
  Scope: only shop/pricing.py and its tests. Show me the diff and a 2-line explanation.

Include an example of the expected behaviour

"15% off 200 should give 170" is clearer than a paragraph, and doubles as a test.

Quick check: Which element lets the agent (and you) know the task is done?

• A friendly tone
• A concrete way to verify, such as tests that must pass
• A long background story
• A random deadline