How to write a task for a coding agent

A good task for a coding agent names four things: the goal, where to work, the limits, and the command that must pass when the work is done. With those, the agent knows when to stop, and you know how to check its work.

Most disappointing agent results come from a vague task, not a weak model. "Fix the login bug" leaves the agent to guess what the bug is, where it lives and what "fixed" means. The steps below turn a vague request into one an agent can finish.

Steps

1. State the goal in one sentence, as an outcome. Say what should be true afterwards, not only what to do. - Vague: "Improve the login." - Clear: "Users on slow networks should not be logged out after 30 seconds."

1. Give the evidence. Paste the exact error, the failing command and its output, or the steps to reproduce. A real error message is worth a paragraph of description.

1. Say where to work. Name the folder or files that matter, and any that are off limits. - "The session code is in src/auth/. Do not change src/billing/."

1. Set the limits. Agents follow constraints well when you state them: - Do not add new dependencies. - Keep the public API the same. - Do not edit or delete existing tests to make them pass. - Match the existing code style.

1. Define done with a command. This is the most important line. Give the exact command that must succeed: - "Done when npm test passes and npm run lint shows no errors." - "Done when pytest tests/test_session.py passes, including a new test for the timeout."

1. Ask for a plan first on big tasks. For anything that touches many files, ask the agent to read the code and propose a plan before it edits. Fix the plan, not the code.

1. Ask for a short report. "When you finish, list the files you changed and why, and anything you were unsure about." This makes your review faster.

1. Keep tasks small. One task, one outcome. Three small tasks give three small diffs you can review, instead of one huge diff you skim.

A template you can copy

Goal: <what should be true when this is done>

Context: <error message, failing command and output, or steps to reproduce>

Where: work in <folders/files>. Do not change <folders/files>.

Limits: no new dependencies; keep the public API the same; do not
edit existing tests to make them pass.

Done when: <exact command> passes.

When finished: list the files you changed, why, and anything you
were unsure about.

A worked example

Goal: users on slow networks are no longer logged out after 30 seconds.

Context: on a throttled connection, the session refresh request takes
about 40 seconds and the client gives up at 30, then logs the user out.
See src/auth/refresh.ts.

Where: src/auth/ only.

Limits: no new dependencies. Keep the refresh endpoint unchanged.

Done when: npm test passes, including a new test that simulates a
40-second refresh.

When finished: list the changed files and explain the fix in two lines.

Put the standing rules in a file

Things that are true for every task, such as how to build, test and lint, belong in a project instructions file in the repository root, not in every prompt. Many agents read such a file automatically; check your tool's docs for the file name it uses.

Doing it with Mel

In Mel, press ctrl+enter (cmd+enter on macOS) to turn what you typed into an agent conversation. Mel adds a few things that help with good tasks:

• Attach the evidence. Select a failed command's block and press ctrl+↑ to attach the command and its output to your prompt, so the agent sees the real error.
• Plan first. Type /plan, or ask the agent to plan before building. The plan opens in a panel beside the conversation, and nothing is changed until you approve it.
• Project memory. Mel's agent keeps short notes per project, such as "tests run with cargo test -p app", and recalls them in later conversations. You can view and delete them in the Memory panel.
• Live checklist. For many-step work the agent posts a task list in the conversation and ticks items off as it goes.
• The finish line. Give a "done when" command and the agent can run it to check its own work. You still run it yourself before you commit.

For a big task, the same prompt works for a team of agents with /orchestrate-agent: the lead splits it into parts, each with its own finish line.

FAQ

How long should a prompt for a coding agent be? Long enough to cover the goal, context, limits and a done command. That is often five to ten lines. Length matters less than a clear finish line.

What is the most important part of an agent task? The "done when" command. It tells the agent when to stop and gives you a way to check the work.

Should I tell the agent which files to change? Name the area if you know it, and name what is off limits. Let the agent find the exact files.

Why does my agent change tests to make them pass? Because nothing told it not to. Add "do not edit existing tests" to your limits, and check test files in the diff.

Should I ask for a plan before code? For tasks that touch more than a couple of files, yes. A plan is cheap to correct; a big diff is not.

• How to review an AI agent's code changes
• How to run several AI agents at once
• How to compare two AI models on the same coding task
• What is an agentic terminal?