To write a task for an AI coding agent, state the goal, point to the relevant files and patterns, set the scope and constraints, and end with acceptance criteria the agent can check itself, such as a test that must pass. This guide covers each part, how to size tasks, good and bad examples, what belongs in project files instead, and a copy-paste template.
- A good agent task has six parts: goal, context, scope, constraints, verifiable acceptance criteria and the deliverable you expect back.
- Give the agent a check it can run, such as tests, a build or a screenshot comparison, so it can iterate until the check passes instead of stopping when the work looks done.
- Size tasks so the result is one reviewable pull request; split anything that touches several unrelated areas.
- Put rules that apply to every task in
CLAUDE.mdorAGENTS.md, and keep the task itself about this one change. - Ask for evidence (test output, commands run, screenshots) rather than a claim that the work is done.
How do you write tasks for AI coding agents?
You write a task for an AI coding agent the way you'd brief a capable contractor who has never seen your codebase: say what outcome you want, where to look, what not to touch, and how both of you will know it's done. The last part matters most. An agent with a check it can run keeps working until the check passes; an agent without one stops when the work looks finished.
Anthropic's Claude Code best practices put it directly: give Claude a check it can run, such as tests, a build or a screenshot to compare. They describe this as the difference between a session you watch and one you walk away from.
A minimal task that works:
Users report that login fails after a session timeout. Check the authflow in src/auth/, especially token refresh. Write a failing test thatreproduces the issue, then fix it. Run the auth tests and show me the output.That's four sentences, and it has a goal, a location, a method and a verifiable finish. Most tasks need little more than that, written carefully.
What goes into a good task for a coding agent?
A good task has six parts. Short tasks may cover some in a phrase; feature work needs all six spelled out.
| Part | What it answers | Example |
|---|---|---|
| Goal | What outcome, for whom, and why | "Let admins export invoices as CSV so finance can reconcile monthly." |
| Context | Where the relevant code and patterns are | "Exports live in src/export/; follow how pdf.ts is structured." |
| Scope | Which files or areas may change | "Change src/export/ and its tests only." |
| Constraints | Rules and limits | "No new dependencies. Keep the public API of exportInvoices unchanged." |
| Acceptance criteria | Checkable conditions for done | "npm test -- export passes, including a new test for names with commas." |
| Deliverable | What you want back | "A branch with commits, and a summary of what changed and how you tested it." |
Goal
Describe the outcome, not the implementation, unless the implementation matters. "Make the dashboard load faster" is a wish. "The dashboard's initial load makes 14 API calls; reduce it to at most 3 by batching the widget queries" is a goal an agent can work toward.
Context
Point to files, existing patterns and sources of truth instead of describing them. In Claude Code you can reference files with @, paste screenshots or give documentation URLs. Pointing to an existing example ("follow the pattern in HotDogWidget.php") is one of the most effective lines you can write, because it answers dozens of style questions at once.
Scope and constraints
Agents tend to fix things they notice along the way. That's helpful in moderation and painful in review. Say which areas may change, which must not, and what's off limits: new dependencies, schema changes, public API changes, touching generated files.
Acceptance criteria
Write conditions the agent can check without you: a named test, a command that must exit with code 0, specific input and output pairs, a screenshot that must match. Then ask for evidence. Anthropic recommends having Claude show the test output, the command it ran and what it returned, or a screenshot, rather than asserting success.
Deliverable
Say what you want at the end: a plan only, a branch, a pull request, a summary with open questions. For unattended work, also say what to do when blocked, for example "If the fix needs a schema change, stop and write up the options instead."
What does a task template for AI agents look like?
Use the same structure every time, so you notice when a part is missing. Copy this into a snippet tool or an issue template:
## Goal[One or two sentences: the outcome and why it matters.]## Context- Relevant code: [files or directories]- Pattern to follow: [an existing file that does something similar]- Background: [links to issue, design, docs, error logs]## Scope- May change: [paths]- Must not change: [paths, public APIs, schemas]## Constraints- [No new dependencies / keep API stable / performance limit / style rule]## Acceptance criteria- [ ] [Named test or new test that must pass]- [ ] [Command that must succeed, e.g. `npm run typecheck`]- [ ] [Behavior check: input X produces Y]## Deliverable- [Plan only | branch | pull request] with a summary of changes, commands run with their output, and any open questions.- If blocked by [condition], stop and explain the options.For larger features, let the agent help write the spec. Claude Code's docs suggest starting with a short description and asking Claude to interview you about implementation, UX, edge cases and tradeoffs, then write the result to SPEC.md and start a fresh session to implement it. The docs add that the most useful specs name the files and interfaces involved, state what's out of scope, and end with an end-to-end verification step.
I want to add team invitations by email. Interview me in detail aboutimplementation, UX, edge cases and tradeoffs. Skip obvious questions anddig into the hard parts. When we're done, write a complete spec to SPEC.md.What do good and bad agent tasks look like?
Bad tasks are vague about the outcome and silent about how to check it. Good tasks are specific about both. Here are three common task types.
Bug fix
Fix the CSV export bug.CSV export on /invoices drops rows when the customer name contains acomma. Expected: such names are quoted per RFC 4180.Code: src/export/csv.ts (toCsvRow); tests in src/export/csv.test.ts.First write a failing test with the name "Acme, Inc.", then fix it.Done when `npm test -- csv` passes and no other export format changes.Show the test output.Feature
Add a calendar widget to the home page.Add a calendar widget to the home page. Look at how existing widgets arebuilt; HotDogWidget.php is a good example, follow its pattern.The widget lets the user pick a month and page forward and backwardby year. Use only libraries already in the codebase.Done when: the widget renders on the home page, the existing widget testspass, and you've added tests for month and year navigation.Plan first and wait for my OK before writing code.Refactor
Clean up the payments module.Refactor src/payments/ so that provider-specific code (Stripe, PayPal)lives behind the PaymentProvider interface in src/payments/provider.ts.Behavior must not change: all tests in src/payments/ must pass beforeand after, with no test edits except import paths.Don't touch webhook handlers in this task.Deliver as a series of small commits, each passing the tests.The better versions share four traits: they name files, point to a pattern or source of truth, limit scope, and define done in a way the agent can verify. For the prompting principles behind this, see our prompt engineering guide.
How big should a task for an AI agent be?
Size a task so the result is one pull request a person can review in one sitting. Small enough that the agent's context stays focused, large enough that the result is worth the review.
Signals a task is too big:
- It touches several unrelated areas (auth, billing and the UI in one task).
- You can't write acceptance criteria without the word "and" five times.
- The agent would need to make product decisions you haven't made.
- The expected diff runs to thousands of lines outside generated files.
Signals a task is too small to plan: you could describe the diff in one sentence. Anthropic's guidance is to skip plan mode for changes like fixing a typo, adding a log line or renaming a variable, and to use it when you're unsure of the approach, the change spans multiple files, or you don't know the code well. In Claude Code, you enter plan mode with Shift+Tab or start with claude --permission-mode plan.
To split a large piece of work, ask the agent: "Break SPEC.md into tasks that each produce one reviewable pull request, in dependency order, each with its own acceptance criteria." Then run them one at a time, or in parallel on separate branches.
If you've corrected the agent twice on the same issue in one session, stop. Start a fresh session with a better task that includes what you learned. Claude Code's docs note that a clean session with a better prompt almost always beats a long session full of corrections.
What belongs in the task, and what belongs in CLAUDE.md or AGENTS.md?
Put rules that apply to every task in a project memory file, and keep each task about one change. Repeating build commands and style rules in every task wastes effort and drifts out of date.
Put in CLAUDE.md or AGENTS.md | Put in the task |
|---|---|
| Build, test and lint commands | Which tests prove this change works |
| Code style that differs from defaults | Patterns to follow for this feature |
| Branch and commit conventions | Files in and out of scope |
| Architecture decisions and gotchas | The goal and acceptance criteria |
| Environment quirks and required variables | Links to the issue, logs or design |
Claude Code reads CLAUDE.md at the start of every session, and Codex reads AGENTS.md files from the project root down to the working directory before doing any work. Keep these files short. Anthropic's test for each line is whether removing it would cause mistakes; if not, cut it. Our CLAUDE.md best practices covers structure and examples.
For rules that must hold with no exceptions, such as "never write to the migrations folder," use a deterministic mechanism like a Claude Code hook rather than a sentence the model might miss.
How do you write tasks that finish without you watching?
Unattended tasks need everything above plus three things: a stopping rule, a definition of what to do when blocked, and an independent check before the work counts as done. Without them, an agent either stops early with a question nobody answers or keeps going in the wrong direction.
Add these lines to tasks you'll queue overnight or run in the background:
Work on a new branch named fix/csv-quoting. Commit after each passing step.Stop when all acceptance criteria pass, or after you've tried twodifferent approaches that fail. If blocked, write BLOCKED.md with whatyou tried, what failed and the options you see, then stop.Before finishing, have a subagent review the diff against these criteriaand report gaps that affect correctness. Fix those, then open a PR withthe test output in the description.Claude Code also supports stronger gates than a sentence in the prompt: a /goal condition that a separate evaluator re-checks after every turn, a Stop hook that blocks the turn from ending until a script passes, or a verification subagent that tries to refute the result. Anthropic's docs describe these as what lets an unattended run finish correctly without you. Our guides to background coding agents and an overnight AI agent workflow cover queueing and morning review in detail.
Where the agent runs matters too: on a laptop, it stops when the lid closes. Orkio rents an always-on cloud box where Claude Code or Codex keep working on tasks you send from your phone or the web, and you review the pull requests later.
What mistakes make AI agent tasks fail?
Most failed agent tasks fail for the same handful of reasons, and each has a simple fix.
| Mistake | What happens | Fix |
|---|---|---|
| No way to verify | The agent stops when the code looks plausible | Name a test or command that must pass |
| Unscoped investigation | "Look into the slowness" reads hundreds of files and fills the context | Name the suspected area, or use a subagent for research |
| Symptom only | The agent suppresses an error instead of fixing it | Ask for the root cause and a failing test first |
| Kitchen-sink session | Unrelated earlier tasks distract the agent | Clear the session between unrelated tasks |
| Hidden decisions | The agent guesses a product choice you hadn't made | Decide first, or ask it to stop and present options |
| Overstuffed memory file | Important rules get lost among hundreds of lines | Prune CLAUDE.md or AGENTS.md and move hard rules into hooks |
The fastest diagnostic is to read your task as if you had never seen the codebase. Every question you'd have to ask is a guess the agent will make.
Your checklist for writing an AI agent task
Before you hit enter, check that the task:
- States the outcome in one or two sentences, including why.
- Names the files, directories or existing pattern to follow.
- Says what may change and what must not.
- Lists constraints: dependencies, APIs, schemas, performance.
- Has acceptance criteria the agent can check itself, ideally a test.
- Asks for evidence: commands run, output, screenshots.
- Says what to deliver and what to do when blocked.
- Fits in one reviewable pull request.
- Leaves project-wide rules to
CLAUDE.mdorAGENTS.md.
Then review the result like any colleague's pull request. Our AI code review guide covers adding an automated first pass.
Frequently asked questions
How long should a task for an AI coding agent be?
Long enough to remove guesswork, which for most tasks is 5 to 20 lines. A one-line fix needs one line. A feature needs a goal, the files involved, constraints and acceptance criteria. If the task runs past a page, it is probably two or three tasks.
Should I let the agent plan before it codes?
Yes, when the change touches several files, when you're unsure of the approach or when you don't know the code well. Anthropic's Claude Code guidance suggests skipping the plan when you could describe the diff in one sentence, such as a typo fix or a renamed variable.
What are acceptance criteria for an AI agent?
They are concrete conditions that decide whether the task is done, written so the agent can check them itself. Good examples are a named test that must pass, a command that must exit cleanly, an exact output for a given input or a screenshot that must match a design.
Why does my coding agent ignore my instructions?
Common causes are vague wording, too many instructions at once, a long project memory file where important rules get lost, and a session cluttered with earlier failed attempts. Shorten the instructions, make the key rule specific, and start a fresh session with a better task.
Can I give an agent several tasks at once?
You can queue several tasks, but give each its own session, branch or worktree so they don't share context or collide in the same files. Bundling unrelated changes into one task produces large diffs that are hard to review.
