How to Write Better Tasks for Coding Agents

Treat the task as a small contract

“Fix the page” forces an agent to infer the bug, intended behavior, allowed scope and definition of done. Sometimes that works. It is also an easy way to get a plausible change that solves the wrong problem.

A stronger task establishes a contract between the requested outcome and the evidence that will demonstrate it.

Five fields that remove ambiguity

For non-trivial work, specify:

1. Goal: what should be different for the user or system?
2. Relevant scope: where is the problem observed, and which subsystem is likely involved?
3. Constraints: what must remain compatible or untouched?
4. Acceptance criteria: which observable conditions define success?
5. Verification: which tests, builds or manual checks should provide evidence?

You do not need a formal template for every typo. The structure becomes more valuable as the blast radius grows.

Weak request vs executable task

Weak:

Fix the mobile navigation.

Stronger:

On viewports below 768px, the header menu closes immediately after the
menu button is tapped.

Goal: keep the menu open until the user selects a link, taps the close
control, or dismisses the menu normally.

Constraints:
- preserve the current desktop navigation;
- use the existing Bootstrap dependency;
- do not duplicate the navigation markup.

Acceptance:
- menu opens on a 390px viewport;
- links remain tappable;
- desktop header is unchanged;
- existing build/check commands pass.

Inspect the implementation first. Report the root cause and changed files.

The second version still lets the agent investigate. It simply removes avoidable uncertainty about the target state.

Do not over-prescribe the implementation

There is a difference between a constraint and a guessed solution. “Do not add a new dependency” is a constraint. “Change line 84 to this exact function” is an implementation instruction and may prevent the agent from finding the actual cause.

When you already know the exact patch, a coding agent may not be necessary. Agentic work is most useful when the goal is clear but investigation and implementation require several steps.

Define when the agent should stop

An agent should not invent product decisions merely to keep moving. State when it should ask for clarification: destructive migrations, ambiguous UX behavior, missing credentials, conflicting requirements or changes outside the requested scope are common boundaries.