How to write a task for an AI coding agent
Jul 14, 2026 · 9 min read · By Priya Nair, Engineering
A good task for an AI coding agent is one a competent new teammate could complete without coming back to ask you a question. That means four things: a clear goal, the part of the codebase involved, concrete acceptance criteria, and how success is tested. Vague tasks produce vague pull requests, and the agent will confidently build the wrong thing if you let it guess. The single biggest lever on agent output quality is not the model. It is how well you scope the request before you hit run.
This is a skill, and it is the same skill that makes you good at delegating to humans. Here is the anatomy of a task that gets you a mergeable pull request on the first try, with examples of what works and what does not.
The anatomy of a good task
Every strong task for an agent has the same four parts. Leave one out and you are hoping the agent guesses right.
- The goal, in one or two sentences. What should be true after this change that is not true now? State the outcome, not the implementation, unless the implementation is the point.
- The location. Point at the files, module, or feature involved. An agent that knows where to look plans faster and wanders less. If you are not sure, name the entry point or the symptom.
- Acceptance criteria. The conditions that make this done. What should the new behavior be? What should not change? What are the edge cases you care about?
- How it is verified. Point to the test that should pass, or ask the agent to add one. An agent that can run your suite will iterate against these criteria on its own before it shows you anything.
You do not need a spec document. Two or three tight sentences that cover those four points beat a page of rambling context.
A vague task vs a clear task
The difference is easiest to see side by side.
| Vague (avoid) | Clear (do this) |
|---|---|
| "Fix the login bug." | "Users with an email containing a plus sign cannot log in. The failure is in the email normalization in AuthController. Logins with plus-addressing should succeed. Add a test that logs in as [email protected] and passes." |
| "Make the export faster." | "The CSV export in ReportsController times out over 50,000 rows. Stream the export instead of building it in memory, and keep the output byte-for-byte identical. The existing export test must still pass." |
| "Add tests." | "The PricingService class has no test coverage. Add unit tests for calculateTotal, including the zero-item cart, the maximum-discount case, and a currency-rounding edge case." |
The clear versions are not longer because they ramble. They are longer because they answer the questions the agent would otherwise have to guess at: where, what done looks like, and how to check.
Scope one task, not a project
The most common mistake is handing an agent a project and calling it a task. "Rebuild the billing system" is not a task. "Add a proration line item to the invoice generator, following the existing line-item pattern" is. A well-scoped task is small enough that the resulting pull request is reviewable in one sitting. If you cannot imagine the diff, the task is too big, and you should break it into a sequence you can review one at a time.
If the pull request would be too large to review carefully, the task was too large to hand over. Scope to the size of a review, not the size of a sprint.
Small tasks also fail cheaply. When an agent misunderstands a tight task, you have lost twenty minutes and a quick review. When it misunderstands a huge one, you have lost a lot more, and the diff is too big to tell where it went wrong.
Give context the agent cannot infer
An agent reads your codebase, so it can infer your conventions, your framework, and your patterns. What it cannot infer is intent and history. Tell it the things that are true but invisible: "we deliberately do not cache this because the data must be fresh," or "match the error-handling style in the OrdersController, not the older PaymentsController." A sentence of intent prevents a plausible-looking change that violates a rule only you knew about. This is the same discipline that makes a plain-English request work in other tools too; the pattern of describing what you want in words and getting structured work back shows up everywhere from code to turning a plain-English question into a database query.
Specify what should not change
Agents are eager. Left unbounded, one can helpfully refactor a file you did not want touched. If a change should be surgical, say so: "do not modify the public API," or "keep the function signature identical," or "change only the validation, not the persistence." Guardrails in the task keep the pull request focused, which keeps your review fast.
Common mistakes that produce bad pull requests
- Ambiguous goals. "Improve" and "clean up" mean nothing to an agent. State the concrete outcome.
- No success condition. Without acceptance criteria or a test, the agent decides for itself when it is done, and it will decide generously.
- Too big. A task that spans ten files and three concerns should be several tasks.
- Missing the why. Skipping the one piece of intent that would have prevented the wrong turn.
- No pointer to location. Making the agent search the whole repo for something you could have named in four words.
Put it together
Writing a good task takes an extra minute and saves you a bad pull request. Start with the outcome, point at the code, say what done looks like, and name the test. Keep it small enough to review in one sitting, and add the one line of intent the agent could not have known. Do that, and the diff you get back is usually the diff you wanted. To see how the agent turns that task into a plan, edit, test, and pull request, read what an AI coding agent is and how it works, then review the result using this guide to reviewing an AI pull request.