Write a coding-agent task brief that can be checked

A coding-agent brief should define the requested behavior, the boundaries of the change and the evidence that would establish completion. Include the repository context needed to begin, but leave implementation choices open unless they are part of the requirement. The goal is an executable decision about done, not a longer prompt.

The distinction predates coding agents. In a June 2025 Reddit discussion, BertRenolds described using a short note for their own infrastructure work but writing acceptance criteria when delegating it: storing a secret in the team's vault was obvious to them and might not be obvious to someone else. That is a report about human teams, not an agent experiment. Its relevance is the missing shared knowledge. ^[1]

An agent cannot recover a requirement that exists only in your expectation. A good brief makes the expensive assumptions explicit before they become code.

Begin with behavior, not a guessed patch

Suppose a hypothetical customer-support dashboard exports filtered tickets to CSV. The bug report says that clicking Export ignores the current status filter. A weak assignment is “fix the export function.” A stronger assignment names a visible result: “Export the same status-filtered ticket set shown in the table, using the existing export columns.”

That statement leaves room to discover whether the bug is in the query builder, request parameters or export handler. It also protects the existing column contract without prescribing a speculative implementation.

Factory's task-specification guidance asks for a bounded outcome, acceptance criteria, verification steps and relevant repository context. GitHub likewise recommends clear scope, acceptance criteria and directions toward relevant files when assigning work to Copilot. These are vendor recommendations, not a measured guarantee for every task. ^{[2] [3]}

Define the examples before asking for implementation

For the dashboard, the important distinction is which tickets appear in the downloaded file. “The button works” does not establish that. Start with a small fixture where the correct output is unambiguous.

The last row deliberately exposes an unresolved question. If the repository or product specification does not establish the pagination contract, the brief is not ready to claim a precise expected count. Ask for that decision rather than letting the agent choose whichever behavior is easiest to test.

Cucumber's Gherkin reference organizes examples around an initial state, an event and an observable outcome. You can use that structure in plain language without adding Cucumber to the project. Executing it still requires real test code and fixtures; a Markdown scenario alone is not an automated test. ^[4]

A compact brief for the example

The following is a NO FEED template illustrated with hypothetical paths. Replace them with actual references before delegation.

Goal
Make ticket export honor the selected status filter while preserving
the existing CSV columns and existing authorization behavior.

Starting context
Repository: support-dashboard; use the assigned feature branch.
Read the filter and export flow under src/tickets/.
Use the existing CSV fixture and the project test instructions.

Required behavior
- Open exports only open tickets from the fixture.
- All retains the existing unrestricted-status behavior.
- No matches retains the header and exports zero ticket rows.
- Column names, order and authorization behavior remain unchanged.
- Resolve the documented pagination contract before implementing it.

Boundaries
Do not redesign the table, add a CSV library or alter the ticket API.
If the intended fix requires those changes, explain the dependency.

Evidence
Show the failing filtered-export case before the fix, then its result
afterward. Run the relevant existing checks and report what each covers.
Record checks that fail, are blocked or were not run separately.

Delivery
Prepare the patch and a short mapping from criteria to evidence.
Do not merge or deploy as part of this task.

This example does not prescribe a universal approval process. Its final boundary reflects the hypothetical owner's authorization. Your brief should state the actions actually allowed for your task, including publication when it has already been authorized.

Keep acceptance independent of the proposed solution

“Add a status argument to exportTickets” could be a useful implementation note, but it is not the acceptance criterion. An agent could add that argument and still fail to use it in the query. The criterion concerns the exported rows.

Likewise, a green test that asserts the new helper was called may only confirm the implementation's shape. Include a check at the boundary where the user receives the result. For this task, parse the produced CSV and compare its ticket identifiers with the expected fixture subset.

Claude Code's best-practice guide recommends giving the agent checks it can run and evidence it can inspect, including tests, build results and visual comparisons. Choose the check for the behavior: a screenshot is useful for a layout change, while CSV membership needs data inspection. ^[5]

Do not require every available test simply to make the brief look rigorous. Name the relevant check, its coverage and any required regression gate. If the agent discovers that the check does not exist or selects no cases, it should report that fact and supply the smallest meaningful verification for the requested behavior.

Give uncertainty an explicit next step

Not every task starts with a finished specification. For discovery work, the accepted output might be two implementation options with affected files, known trade-offs and the decision that blocks progress. That can be a complete task without any code change.

For implementation work, distinguish a missing product decision from a routine engineering choice. The CSV pagination contract belongs to the former. The name of a private helper normally belongs to the latter. Requiring approval for both slows the work without clarifying the outcome.

If the task changes during execution, update the brief and mark the superseded criterion. A chat message saying “actually include archived tickets” should not leave the old exclusion requirement silently competing with the new one.

Our article on understanding completed agent changes^[6] concerns the review after implementation. This brief starts earlier: it gives that review a concrete behavior to inspect.

Before assigning the next ticket, ask a colleague—or a fresh agent session—to describe one incorrect implementation that would still satisfy your wording. If it can, tighten the criterion that permits it. Then delegate the bounded change with the evidence requirement attached.