The Shape of a Good Agent Task Description

Writing good task descriptions for agents is the actual skill of the agent era. After a year of watching agents succeed and fail on similar problems, I can trace most of the variance to the shape of the task description. Good descriptions have a specific structure.

The Five Sections

1. Goal: one sentence of outcome
2. Context: the minimum files or facts the agent needs
3. Constraints: what must remain true after the task
4. Definition of done: how the agent verifies completion
5. Escape hatch: what to do if blocked

Every successful task description I have written has all five. Every failed one is missing at least two.

An Example That Works

Goal: add pagination to the posts list endpoint.
 
Context: src/api/posts.ts, src/types/post.ts, existing tests in posts.test.ts.
 
Constraints: keep current response shape backwards compatible;
  pagination params are query string only.
 
Definition of done: existing tests pass;
  two new tests cover first page and last page;
  lint passes.
 
Escape hatch: if pagination would break a consumer, stop and flag.

Short, specific, complete. The agent has no reason to guess and no excuse to overreach.

Why Each Section Matters

• Goal: stops the agent from solving the wrong problem
• Context: stops the agent from reading the whole codebase
• Constraints: stops the agent from breaking what works
• Definition of done: gives both of you the same finish line
• Escape hatch: prevents the agent from forcing a bad answer

The escape hatch is the underrated one. Without it, agents sometimes push through ambiguity by guessing. With it, they stop and ask.

The Length Sweet Spot

A good task description fits on one screen. Longer means you are smuggling architectural decisions into the task. Shorter means you are leaving the agent to guess. Half a page is about right for most non-trivial tasks.

What Changes For Larger Tasks

Large tasks get decomposed. Each subtask gets its own five-section description. The decomposition is the actual work. Once the subtasks are well defined, the agent finishing them is fast.

The Feedback Loop

After every agent task, I reread my description and note what should have been clearer. Over six months the descriptions got shorter and more effective. The skill is real and it compounds.

Amazon's working backwards method maps roughly onto this structure and is worth reading.

The Common Failure Modes

The three failure modes I see most often on task descriptions are: goal too broad, context too wide, definition of done too vague. Each one compounds. A broad goal paired with wide context and vague completion criteria produces agent output that wanders and cannot be graded. Tightening any one of the three helps. Tightening all three transforms the result.

The Written Record

I save every task description I write in a folder, organized by project. Six months later I can grep for the shape of a task I handled before and reuse the description as a template. The descriptions accumulate into a personal library that speeds up every new task. The skill is the descriptions.

What I Tell Other Builders

Spend more time on the description than on the prompt. The description shapes every downstream output. A good description makes the agent look smart. A bad description makes the agent look like a tool that does not work. The responsibility is on the writer, and the leverage is enormous.