How to write a task for a coding agent: a template that works

Short answer: a good task for a coding agent has five parts: the goal in one sentence, the context (which files and why), the constraints (what not to touch), a done condition you can check, and how to test it. Agents fail far more often on vague tasks than on hard ones.

The fastest way to get better results from Claude Code, Codex, Gemini CLI or Cursor CLI is not a bigger model. It is a clearer task. Here is the template we use every day, with examples.

Disclosure: we build Zokie, an agent IDE where every task is a card an agent picks up. The template works in any tool.

The five-part template

Goal: <one sentence: what should be true when this is done>
Context: <files, screens or endpoints involved, and why this matters>
Constraints: <what must not change; style or library rules>
Done when: <an observable result you can check>
Test: <the command or steps that prove it>

1. Goal

One sentence, written as an outcome. "Users can reset their password from the login page", not "work on password reset".

2. Context

Point at the files or areas involved. Agents can search, but naming src/auth/reset.ts and the email template saves time and keeps the change small.

3. Constraints

Say what must not change: public APIs, database schema, a design system, a performance budget. Agents tend to "improve" nearby code unless told not to.

4. Done when

Describe a result you can check without reading the code: "The reset email arrives and the link works once", "The page loads in under one second on a phone".

5. Test

Give the command or the manual steps. An agent that can run the tests checks its own work before it hands the change back.

Before and after

Vague: "The dashboard is slow, fix it."

Clear:

Goal: the dashboard loads in under one second for an account with 1,000 projects. Context: api/projects/list.ts loads every project and its tasks in a loop. Constraints: do not change the response shape; the mobile app reads it. Done when: the list endpoint makes at most two database queries, whatever the number of projects. Test: npm test api/projects and the timing in scripts/bench-dashboard.ts.

The second version gives the agent a target, a starting point, a boundary and a way to prove it is finished.

Five habits that make tasks work

• One change per task. Split "fix the bug and refactor the module" into two tasks you can review separately.
• Ask for a plan on anything big. "Propose a plan, do not edit yet" catches wrong assumptions early.
• Include the error. Paste the full error message and the steps that cause it.
• Say who it is for. "This is for non-technical admins" changes wording, defaults and error messages.
• Write the rules down once. Repeated rules belong in your project's CLAUDE.md or AGENTS.md, not in every task. See our guide to CLAUDE.md and AGENTS.md.

Turning tasks into a backlog

When tasks follow one template, you can queue several and let agents work through them in parallel, each on its own branch. In Zokie each task is a card on the Board: an agent picks it up, works in its own git worktree, and the card moves to review with a diff when it is done. You can also schedule tasks to run on their own.

FAQ

How long should a prompt for a coding agent be?

Usually five to ten lines. Long enough to state the goal, context, constraints, done condition and test; short enough that every line matters.

Should I tell the agent which files to change?

Yes, when you know them. Naming files keeps the change small and saves the agent searching. If you do not know, ask it to find the files and propose a plan first.

Why does my coding agent change things I did not ask for?

Usually because the task did not say what to leave alone. Add constraints such as "do not change the public API" or "only edit files in this folder".

Does the same template work for Claude Code, Codex and Gemini CLI?

Yes. All of them do better with a clear goal, named context, explicit constraints and a way to test the result.