Preparing a task before you hand it to a cloud coding agent

Why a cloud task needs more than a prompt

In an interactive session, an engineer notices a wrong turn and corrects it. A cloud agent works alone in a remote environment, so every open question gets answered by a guess, and the guess arrives later as a finished pull request. GitHub's guidance for its cloud agent puts it plainly: think of the issue you assign as the prompt, and give it a clear description, complete acceptance criteria and directions about which files to change.

Anthropic's guidance on agent evaluations offers a test that transfers well: a good task is one where two experts would independently reach the same pass or fail verdict, and everything the checks verify is stated in the task. A brief that meets that bar is also one a reviewer can check without replaying the session.

A brief in eight parts

This template works for any cloud agent that reads an issue or a prompt. The filled-in example is hypothetical.

## Goal
GET /v1/invoices returns CSV when the client sends Accept: text/csv.

## Context
- Read src/api/invoices/list.ts and its tests first
- Column order is defined in docs/exports.md

## Scope
- CSV output for this endpoint, with the same filters as JSON

## Non-goals
- Other endpoints, streaming, spreadsheet formats, UI changes

## Acceptance checks
- pnpm test:unit passes, with new tests for CSV output
- Accept: text/csv returns the documented columns in order
- Existing JSON tests pass unchanged

## Environment
- Tests use fixtures in test/fixtures/invoices; no database, no secrets

## Stop and ask before
- Adding a dependency, changing the shared serializer, editing CI

## Hand back
- Pull request: what changed, commands run with results,
  anything not verified, open questions

Non-goals and the stop list deserve the most care. They name the plausible extra work an agent might otherwise take on, and the changes that need a person to decide.

Three questions before delegating

• Could a reviewer who did not write the brief judge whether the result is done?
• Can the agent's environment run the acceptance checks without a person, including services and test data?
• Is the task free of production data, credentials and irreversible actions?

A no to any of them means interactive work or a smaller task. GitHub's own list of tasks better kept by people matches this: broad refactoring that needs knowledge across repositories, deep domain logic, production-critical issues, work touching security, personal data or authentication, incident response, and anything with unclear requirements.

Large work can still go to an agent in phases. OpenAI's cookbook recipe for iterating with Codex describes phase files, each small enough to implement and verify independently, with observable acceptance criteria, an approval gate and an explicit stop condition.

Decide where the agent stops

The stop list in a brief is an instruction, and the agent can misread it. The same cookbook recipe keeps commits, pushes, deployments, credentials and external writes behind separate explicit approval. OpenAI's article on Codex as a platform describes the same split from the system side: the host application decides where the agent runs, which tools it can use, which actions need approval and how results return to the system of record.

In practice that means the brief says what to stop for, and the environment makes it true: credentials scoped to the task, pushes only to the agent's own branch, and branch protection that keeps merges with people.

What comes back, and who picks it up

The engineer who delegated the task owns the result and reads it first. A pull request that states what changed, which commands ran with which results, what was not verified and what remains open lets that engineer decide quickly whether to approve it for review, send it back or finish it by hand. Someone else does the approving review.

When a result misses the brief, find out what the brief left open before trying again. Then choose between a few targeted review comments and a new run from a sharper brief, and fold what was missing back into the brief so it becomes the template for the next similar task. On GitHub, batching comments into one review lets Copilot work on all of them at once instead of comment by comment.

Spec-driven development guideBranch protection for agent pull requests