A good agent task has four parts: context, a definition of done, boundaries, and a way to verify. It takes five minutes to write and saves most of the repair cycles that follow a vague request.
Context the agent cannot guess. The agent sees the code, not why it looks that way. One line on why the change is needed, and one line on what you already tried, kills most wrong directions. If one file is the center of the problem, name it.
A definition of done before you start. "Fix the form" is open-ended. "The form saves, shows an error on an empty field, and the existing tests pass" is checkable. An explicit definition of done turns your job from supervising every step into one review at the end.
Boundaries in writing. An agent that finds an adjacent problem tends to fix that too. Write what is in scope and what stays out: which folder it may touch, whether it may change an existing API, whether it may upgrade a dependency. The boundary becomes part of the task, not a negotiation after the result.
A check that proves the result works. Write how to verify: which command runs the tests, and what the expected result is. The agent checks itself before handing back, and you look at proof, not at a feeling.
A full task in four lines: "checkout.ts has a bug: double-clicking submit creates two orders. Done = double-click creates one order, all tests pass. Boundaries = only checkout.ts and its tests, no dependency upgrades. Verify = npm test checkout."
Five minutes of writing, against two or three repair cycles of fifteen minutes each. Most of those cycles start with a task that is missing one of the four parts.
The full guide (in English, with FAQ): https://ofershap.github.io/en/posts/agent-task-spec-first-try/
Original (Hebrew): https://ofershap.github.io/posts/agent-task-spec-first-try/
This article was condensed from my Hebrew guide with AI assistance, and I reviewed it before publishing.
Top comments (0)