Writing a task spec an agent can actually run

A handed-over task has two readers with opposite needs, and most templates serve only one of them.

When you write a ticket for a person, you can be vague about the obvious parts, because the reader shares your context. When you write one for a coding agent, the obvious parts are exactly what goes wrong — the agent will happily pick the wrong directory, the wrong test runner, or the wrong branch, and it will do it confidently.

But if you write only for the agent, you get a wall of paths and flags that the human reviewing the result cannot skim. They can no longer answer the one question that matters at review time: was this the right thing to build?

The two readers

So a good spec is really two documents stapled together:

• The human brief — two or three sentences on intent. What outcome are we buying, and how will we know it worked? This is what gets read at review.
• The agent brief — exact paths, exact commands, exact acceptance checks. No judgement calls left implicit.

Someone else has written this pattern up more carefully than I will here; if the idea is new to you, start with the dual-prompt write-up on task design, which is where I first saw the split named properly.

Six things to pin down before handing it over

1. Entry point. The repo, the branch, and the directory the work starts in. Not “the API” — the path.
2. Definition of done as a command. If done cannot be expressed as a command that exits zero, the agent is guessing and so is the reviewer. npm test -- --run auth beats “tests should pass”.
3. The blast radius. Which files or directories are in scope, and which are explicitly off limits. Agents are bad at inferring that a migration file is sacred.
4. Prior art. One pointer to an existing thing in the codebase that already does something similar. This single line does more for output quality than any amount of prose.
5. What you already ruled out. If you tried the obvious approach and it failed, say so. Otherwise you will get it back.
6. Who to ask. The one decision the agent is not allowed to make alone, and who owns it.

The failure mode to watch for

The most expensive spec is not the vague one. It is the one that is precise about the how and silent about the why. You get back exactly what you asked for, it takes forty minutes to review, and only then does someone notice the underlying request was wrong. Intent first, then instructions.