How to write a task for a coding agent

A clear task means less guessing for the agent. It does not promise correct code, so say how you will check the result too.

Give a coding agent a fuzzy task and it may quietly fill the gaps with assumptions. A clearer task means less of that guessing. It will not guarantee correct code, so a good task also says how you will check the result.

A quick word on speed, because it is tempting to trust the feeling. In a 2025 controlled study with random assignment, METR followed 16 experienced open-source developers through 246 tasks in repositories they knew well, using early-2025 tools. With AI, the tasks took 19% longer, even though the developers expected to go faster. That result belongs to those tools and that setting. In February 2026 METR wrote that newer tools probably help more, but that selection effects, in who took part and in which tasks they chose to submit, made the new estimate unreliable. What I take from it: the feeling of speed is not a measurement, so check the work.

Start with what done looks like

Before anything else, decide how you will know the task is finished. When requirements are missing, the agent has to guess. Write the outcome in one sentence, then the check that shows it.

The two vendor guides lean on different halves of this. Claude Code's guide suggests giving the agent something it can run to verify its own work: tests, a command, a screenshot to compare. GitHub's Copilot guide puts the weight on clear scope and acceptance criteria. You want both.

Practice on something low-risk. Anything that touches login, permissions or payments deserves much more care: explicit tests for the failure cases, and a person doing a security review.

Give the context that matters, not all of it

Name the files involved, point to one existing example worth following, and state the constraint that matters. Say what must stay untouched. Resist pasting everything you know, because a long task can bury the details that count.

If the change spans several files, ask for a plan first and read it. A reviewed plan can catch a wrong turn before any code exists.

A full example (hypothetical)

Here is an imagined Python project.

Goal: add a --dry-run flag to the export command, so it prints what it would write and changes nothing.

Context: the command lives in myapp/export.py. Handle the flag the way --verbose is handled in myapp/sync.py, and reuse the existing writer class.

Constraints: no new dependencies, no changes to deploy or CI files, never read or print secrets or environment files, nothing changed outside myapp/ and tests/. Any test that exercises the writer runs only in an isolated temporary directory, never in a real output location.

Done when: python -m pytest tests/test_export.py runs without errors and every test passes, including two new ones. One checks that --dry-run writes no files. The other checks that a normal run still writes them. Report back with the test output and the list of changed files.

Out of scope: renaming flags and refactoring the writer.

What you check as the human

Read the whole diff. Confirm that the new --dry-run test fails without the change and passes with it, and that the normal-run test passes both before and after. Check that the writer tests use a temporary directory, that nothing outside myapp/ and tests/ changed, and that no dependency or config file moved. Then run the command yourself, once with the flag and once without, in a scratch folder.

Before you approve, make sure you can explain the change in your own words. If you cannot, ask the agent to clarify it, and split the task if it was too big.

The template

Five fields cover most tasks: Goal, Context, Constraints, Done when, Out of scope.

DORA's 2025 research describes AI as an amplifier of a team and its practices, which means it amplifies strengths and weaknesses alike. So my advice is to start with clear tasks, tests, and small changes that someone reviews.

Sources

• METR: Measuring the impact of early-2025 AI on experienced open-source developer productivity
• METR: We are changing our developer productivity experiment design (Feb 2026)
• Claude Code: best practices
• GitHub Copilot: best practices for using Copilot to work on tasks
• DORA: State of AI-assisted Software Development 2025

Originally published at https://withavi.ai/en/posts/spec-for-ai-coding-agent/

Avi.Bi