TIPS & TRICKS · AGENTS · PROMPTING

How to Write a Task a Coding Agent Can Finish

Brief a coding agent like a capable new teammate. State the goal, give the context it cannot discover, and say how you will check the result, with examples.

3 Nov 2026 · 5 min read

Most disappointing agent sessions start with a one-line request. “Fix the login bug.” “Add dark mode.” The agent does something, it looks plausible, and twenty minutes later you find it fixed a different bug, or added a theme toggle nobody asked for.

The model is rarely the problem. The brief is. A coding agent is like a sharp engineer on their first day: quick, tireless, and missing everything you know but did not write down. A good task has three parts: the goal, the context, and the acceptance check.

1. The goal: what done looks like

Say what should be true when the work is finished, not just which area to touch.

• Weak: “Look at the signup form.”
• Strong: “New users who sign up with an email that already exists should see ‘That email is already registered’ under the email field, instead of the page going blank.”

The strong version names the user, the trigger and the visible result. The agent can now tell when it is finished, and so can you.

If there are things you do not want, say those too. “Do not change the database schema.” “Keep the public API the same.” Limits are part of the goal, and agents respect them far more reliably when they are written down than when they are implied.

2. The context: what it cannot discover

An agent can read your repository, run commands and search. It cannot read your mind, your team chat or last week’s incident review. Give it the things that are not in the code:

• Where to start. “The form is in src/pages/signup.astro; the API is src/pages/api/signup.ts.” This saves many turns of searching.
• Why it matters. “Support gets ten tickets a day about this.” Knowing the stakes helps the agent choose between a quick patch and a careful fix.
• What you already tried. “Catching the error in the form did not help; the API returns 500, not 409.” This stops it repeating your dead ends.
• House rules. “We use the existing Field component for errors; no new CSS files.” Better still, keep these in a project instructions file so you do not retype them.

You do not need to explain how the code works. The agent can read it. Spend your words on facts it would otherwise have to guess.

3. The acceptance check: how you will verify it

This is the part people skip, and it matters most. Tell the agent how the result will be checked, ideally with something it can run itself:

• “Add a test in signup.test.ts that posts an existing email and expects a 409 with that message. All tests must pass with npm test.”
• “Run npm run build; it must finish with no new warnings.”
• “Open /signup at 375 px wide and confirm the message does not cause sideways scrolling.”

An agent with a check it can run will loop: try, check, fix, check again. An agent without one will stop at the first version that looks right. The check turns “probably done” into “done”.

If no automatic check exists, describe the manual one: “I will try it with an existing email and a new one; both must behave correctly.” Even that makes the agent think about both cases.

A worked example

Here is a weak task, and the same task rewritten.

Before

Signup is broken for existing emails, please fix.

After

Goal: when someone signs up with an email that is already registered, the signup form should show “That email is already registered” under the email field. Today the page goes blank.

Context: the form is src/pages/signup.astro, the endpoint is src/pages/api/signup.ts. The endpoint currently throws on the unique-constraint error and returns 500. Use the existing Field error slot; do not add new styles. Do not change the user table.

Done when: the endpoint returns 409 with that message, the form shows it, a new test covers the duplicate case, and npm test and npm run build both pass. Tell me what you changed and anything you were unsure about.

It took two extra minutes to write. It will save far more than that in back-and-forth, and the result will match what you actually wanted.

Size the task to one sitting

A task an agent can finish is also a task that fits in one focused session. “Rebuild the billing system” is not a task; it is a project. Split it until each piece has its own clear goal and its own check: “add the invoice table and migration, with a test that inserts and reads one row” is something an agent can finish and you can review in one go.

A useful rule: if you cannot write the acceptance check in one or two sentences, the task is too big or too vague.

Ask for a short report

End your brief by asking for a summary: what changed, how it was verified, and anything the agent was unsure about or chose not to do. That last part is gold. It surfaces the assumptions you need to check, instead of leaving them buried in a diff.

Takeaway: every task gets three things: a goal that describes what is true when it is done, the context the agent cannot find on its own, and an acceptance check it can run. If you cannot write the check, the task is not ready.