Get featured

How to give an AI coding agent a clear task: scope, context and done-checks

Guide · checked against the docs on

An agent can only build what you describe. Anthropic's Claude Code docs say: "The more precise your instructions, the fewer corrections you'll need."

This guide shows how to write one clear task: what to change, which files matter, what rules to follow, and how you'll know it's done. It's quoted from Anthropic, OpenAI, Cursor, GitHub and VS Code docs, checked Oct 2026.

Not affiliated with or endorsed by Anthropic, OpenAI, Anysphere, GitHub or Microsoft. Check their current docs before relying on these details.

For plan-mode keys, committing first and undo, see prompts that stop AI breaking your code. This guide doesn't repeat them.

Step 1: Use four parts

OpenAI's Codex docs split a task into four parts:

OpenAI says this "helps Codex stay scoped, make fewer assumptions, and produce work that's easier to review." The same four parts work in any agent.

GitHub suggests a similar order for Copilot: "first give Copilot a broad description of the goal or scenario. Then list any specific requirements."

Step 2: Keep the scope small

VS Code's docs say: "Choose a small task and define an observable result." For bigger work, "decompose it into smaller, well-scoped steps."

GitHub's Copilot docs agree: "If you want Copilot to complete a complex or large task, break the task into multiple simple, small tasks."

Step 3: Point at the files

Don't make the agent guess where code lives. Anthropic says to "Reference files with @ instead of describing where code lives." Each tool has its own way:

VS Code also says to "Provide the relevant files, errors, constraints, and existing test commands."

Rules you give on every task, like your test command or code style, belong in a project file instead. See AGENTS.md and CLAUDE.md.

Step 4: Be specific, and show examples

Vague words make the agent guess. GitHub's example: "don't ask 'what does this do' if 'this' could be the current file, the last Copilot response, or a specific code block." Ask "What does the createUser function do?" instead.

Anthropic's docs give a before and after. Before: "add tests for foo.py". After: "write a test for foo.py covering the edge case where the user is logged out."

Examples help too. GitHub says "You can provide example input data, example outputs, and example implementations," and "Unit tests can also serve as examples." VS Code suggests you "Describe expected behavior or include example input and output," such as validateEmail("user@example.com") returns true.

Step 5: Say how it will prove it's done

This is the "done when" part, and it matters most. Anthropic says to "Give Claude a check it can run: tests, a build, a screenshot to compare." Without one, "'looks done' is the only signal available, and you become the verification loop".

Ask for proof, not just "done". Anthropic suggests you "Have Claude show evidence rather than asserting success: the test output, the command it ran and what it returned, or a screenshot of the result."

OpenAI says Codex can test and check its work, "but only if it knows what 'good' looks like." VS Code says to "Provide test cases, expected results, or acceptance criteria so the AI can verify its own work." Cursor's agent can also "Control a browser to take screenshots, test applications, and verify visual changes."

Our advice, not a vendor quote: for anything that touches users or data, add error handling and logging to your "done when" list, without secrets in the logs. OWASP's list of things not to log includes "Access tokens", "Authentication passwords" and "Database connection strings".

Step 6: Plan first, or skip it

For big or unclear work, plan first. OpenAI says: "If the task is complex, ambiguous, or hard to describe well, ask Codex to plan before it starts coding." Cursor says "For larger changes, spend extra time creating a precise, well-scoped plan." Anthropic suggests that "for larger features have Claude interview you and write a spec before you start implementing."

For small work, skip it. Anthropic's rule: "If you could describe the diff in one sentence, skip the plan."

Step 7: Fix it early

Anthropic says to "Correct Claude as soon as you notice it going off track." VS Code says to "Refine responses by adding constraints or corrections in follow-up messages rather than rewriting the entire prompt."

If a planned task goes wrong, Cursor suggests a reset instead: "Revert the changes, refine the plan to be more specific about what you need, and run it again."

An example task

Here's a task written with the four parts (we haven't tried it ourselves):

Goal: add empty-state text to the results view.
Context: @src/ResultsView.tsx and its tests.
Constraints: change only that view and its tests; follow existing patterns.
Done when: the existing tests pass and you show me the test output.

After the agent finishes

A clear task doesn't replace checking the work. VS Code says: "When the agent finishes, inspect every changed file and run the relevant tests yourself." See how to review AI-written code.

Next steps

Not affiliated with or endorsed by Anthropic, OpenAI, Anysphere, GitHub or Microsoft. Check their current docs before relying on these details.