How to write a task an AI coding agent can finish

The short answer to how to write a task an AI coding agent can finish is to give it five things: one outcome, a scope, the dependencies it relies on, explicit completion criteria and the check that proves them. Agents rarely stall because they cannot write the code. They stall, or overrun, because nothing told them where the task ends. Without an end, a session stops when the output looks plausible, or keeps going into neighboring code because that looked related too. A finishable task reads like a short contract: what should be different afterwards, where the agent may work, what it can assume, and how both of you will know it is done. This article shows each part, a weak and a strong version of the same task, and the habits that make a well-meant task unfinishable. It pairs with giving each task bounded context, which covers what the agent should read alongside the task.

The five parts of a finishable task

Outcome. One observable change, written as behavior: checkout totals truncate fractional cents, rather than improve the money code. If you need the word and to describe the outcome, you probably have two tasks.

Scope. The files or modules the agent may change, and the ones it must not. Naming what is out of scope matters most when a shared module sits nearby.

Dependencies. What must already be true, such as a helper that exists or a migration that has run, and what else relies on the code being changed. Agents do not know which other features import a shared function unless you tell them or they search for it.

Completion criteria. Two to five statements a reviewer can check, each one observable: a test exists and passes, an endpoint returns a field, an unchanged module still behaves the same.

The check. The exact command that proves the criteria, usually the project's test command plus the specific new tests. A criterion with no check is a hope, and the agent will report it as met anyway.

A weak task and a strong one

Weak: Fix the rounding bug in checkout and tidy up the money helpers.

This invites the agent to edit the shared helper, because that is where rounding lives, and nothing tells it who else uses the helper. A disposable test project from BRAIN FLUID's development shows how that goes. A scripted change turned round(value * 100) into int(value * 100) inside a shared cents() helper. The checkout check total(1.239) == 123 passed. The CSV export check row(1.235) == "124" failed with "123", because the export also imported the helper and that relationship had never been written down.

Strong: Outcome: checkout totals truncate fractional cents. Scope: src/checkout/total.py and tests/test_checkout.py. Out of scope: src/money.py, which the CSV export also uses. Depends on: the existing cents() helper, unchanged. Done when: a new test, test_total_truncates, passes, the export tests pass unchanged, and the full suite passes. Check: the project test command.

The strong version is a few lines longer and removes the most likely wrong turn. It also hands the reviewer a list to tick.

Write the check before the agent runs

A check is only useful if it fails before the change and passes after it. Run it against the untouched code first. If it already passes, it proves nothing about the task. In a benchmark run on development builds, each of six synthetic coding tasks had an independent correctness check that failed on the untouched fixture, and all 24 counted runs passed it afterwards. That is the pattern to copy: the check exists, has been seen to fail, and does not depend on the agent's description of its own work.

The second rule is that the agent's report is not the check. In the same development build testing as the rounding example, a completion report asserting a pass was accepted on one route while the app still failed a test [D1]. In a later development build, owner-configured checks run independently, and with the broken code the card stayed in VERIFY despite the agent's passing claim [D3]. Whatever tool you use, run the check yourself or have something other than the agent run it. For choosing how much checking a task deserves, see proportionate checks.

Size, stop conditions and what to leave out

Size a task so that you can review its diff in one sitting. If the completion criteria grow past five items, or the scope crosses more than one module boundary, split it and record the order between the parts.

Tell the agent when to stop and ask instead of guessing: when the change would touch an out-of-scope file, when a test outside the task starts failing, or when two reasonable designs exist and the task does not choose between them. Knowing when an agent should stop and ask covers this in more depth.

Tell it what to do with discovered work: write it down as a follow-up, do not do it. Otherwise a task to fix one bug turns into a refactor nobody asked for.

Leave out the history. A task does not need the story of how the bug was found or a pasted chat transcript. Link to the decision record if one exists and state the decision in one line. Long background makes the outcome harder to find and gives the agent more material to misread.

QUESTIONS

How long should a task description for an AI coding agent be?

Usually five to fifteen lines: one outcome, a scope list, dependencies, two to five completion criteria and the check command. Shorter than that and something important is usually missing, often the out-of-scope list. Much longer and the outcome gets buried in background. Put history in a linked record and keep the task itself about what must be true when it is done.

Should I tell an AI agent which tests to run?

Yes. Name the exact command and the specific new tests, and say that the full suite must pass too. Agents left to choose tend to run the narrowest test that covers their change, which is how a regression in another feature slips through. Run the command yourself on the untouched code first, so you know the new tests fail before the change.

What should an AI agent do with extra work it finds during a task?

Record it and leave it. The task should say that discovered work becomes a follow-up note or a new task with its own scope and check, not an addition to the current diff. That keeps the diff reviewable and the completion criteria meaningful. You decide later whether the follow-up is needed, duplicates something that exists or can wait.

RELATED GUIDES

• How to create a project card in BRAIN FLUID Desk

RELATED HARNESS PAGES

• Bounded task context Bounded task context: give an agent the slice of a project one task needs, chosen by relationship, capped in size, with omissions stated.
• Choosing proportionate checks for each AI coding task Choosing proportionate checks for each AI coding task: one check that proves the criterion, a fast baseline, and clear rules for widening.
• Self-reported vs independently run checks for AI agent work Self-reported vs independently run checks for AI agent work: why an agent's own "tests pass" is weaker than a check the system runs itself.
• When an autonomous agent run should stop and ask When an autonomous agent run should stop and ask: failed checks, missing approval, open blockers, impact obligations, out-of-scope writes or uncertain state.
• Breaking a large refactor into agent-sized tasks Breaking a large refactor into agent-sized tasks: expand, migrate and contract in ordered steps that each keep the build green and have a check.
• Organizing a repository so AI agents can navigate it Organizing a repository so AI agents can navigate it: a short README map, one test command, consistent layout, small modules, clear entry points.