# Writing a Task the Agent Can Succeed At — Coding Agents & AI-Assisted Development

Source: https://www.geekswithgeeks.com/en/coding-agents/w-spec

> Give a clear goal, constraints, pointers and a way to check success.

## 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.

![Four habits: specify, test first, go small, isolate.](assets/figures/coding-agents/section-4-map.svg) — Figure 4.1 — Specify, test first, go small and isolate.

## A weak and a strong task

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

```text
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.

**Quiz:** Which element lets the agent (and you) know the task is done?

- [ ] A friendly tone
- [x] A concrete way to verify, such as tests that must pass
- [ ] A long background story
- [ ] A random deadline

*Answer:* A concrete way to verify, such as tests that must pass. Without a check, "done" is just the agent's opinion.