Write a task brief for an agent

Describe a change that a reviewer can assess

“Add customer export” leaves several decisions open. Who can export records? Which records and fields are included? What happens when a request fails? An agent can fill these gaps with plausible choices. Those choices can still be wrong for the business.

Start with the user and the problem. Then describe the required behavior. Include the evidence that will show whether the result is acceptable.

A brief should reduce uncertainty without fixing every internal design choice. Specify a required data boundary. Let the implementation use the existing repository patterns unless there is a reason to change them.

Use a concrete example

The following brief is for a fictional support application. It is an educational example, not a complete production specification.

Outcome: A support manager can download a customer list.
Actor: A manager in the current organization.
Data: Active customers in that organization only.
Fields: Customer ID, company name, and account status.
Format: UTF-8 CSV with a header row.
Denied request: Return the existing authorization error.
Empty result: Return a valid CSV with only the header.
Scope: Use the existing export route and audit pattern.
Excluded: No new roles, dependencies, or deployment.
Evidence: Tests for allowed, denied, empty, and cross-organization requests.

This brief identifies useful behavior and limits. It also exposes further questions. Should the system limit export size? Can a field contain a spreadsheet formula? Who can access the audit record? Resolve consequential questions before implementation. Do not treat the example as a universal checklist.

Separate requirements from assumptions

A requirement states behavior that the change must satisfy. An assumption is a fact you have not yet verified. Keep them separate.

For example, “Use the existing audit pattern” assumes that a suitable pattern exists. Ask the agent to find it. If the repository has none, the agent should report the missing dependency before inventing a new audit system.

A constraint can also conflict with the outcome. The existing route might return every organization by design. The agent should show the conflict and propose a limited correction. It should not silently remove the data boundary or expand the task into an architecture rewrite.

Make completion include evidence

Request a delivery summary that explains the final behavior, changed scope, and checks performed. Require exact commands and results where they matter. Distinguish a check that passed from a check that could not run.

The pull request should preserve the reason for the change. A later maintainer may see the code without the original conversation. Include enough context to explain why the export excludes particular fields and how access is enforced.

Google’s change-description guidance is a useful reference for this record. The description should explain the change and its purpose. Keep the record aligned with the final implementation after review changes.

Keep the brief proportional

A small text correction can use a short brief. A data export needs more detail because its failures can expose information. A new payment workflow needs still more analysis and review.

Do not measure brief quality by length. Ask whether a competent reviewer could distinguish a correct result from an incorrect one. If two reasonable implementations would disagree about a consequential behavior, clarify that behavior first.