The best task brief tells an agent what success looks like and where to look, then leaves implementation details open until it inspects the repository. You can use the same structure in any coding CLI.
Start with a result a person can check
'Make the app better' has no stopping point. 'The settings form saves a display name, shows success, and preserves the value after refresh' does. If you cannot name a visible behavior, a failing test, or an output artifact, spend a few minutes defining one before launching another agent.
Give the minimum useful context
Name the repository area, relevant issue or screenshot, and the command that reproduces the problem. Do not paste a long transcript by default. Let the agent inspect files and state its plan. Keep durable project rules in the repository's supported instruction file; this brief is for one task.
Write acceptance checks before implementation
Separate required behavior from implementation preference. For a UI change, include one desktop and one mobile check if both matter. For a bug, give actual and expected behavior. For an API change, name a response or failure condition. Ask the agent to run relevant tests and report the exact commands and results, including what it could not run.
Set scope and decision points
List files or behaviors that must stay unchanged when a boundary matters. Tell the agent to ask before changing a public API, data model, authentication path, or deployment setting. This is more useful than a vague instruction to 'be careful.' If the task spans several independent outcomes, split it into separate briefs and branches.
Request a reviewable handoff
At the end, ask for changed files, behavior demonstrated, test evidence, open risks, and the branch or PR. In Canopy, open the preview and diff beside the session to verify those claims. A summary is an index into evidence, not proof that the feature works.
Copyable resources
Copyable task brief
Replace the bracketed fields; delete fields that do not apply.
Goal: [one observable outcome]
Project area: [repository, component, page, or service]
Evidence: [issue, screenshot, failing command, actual behavior]
Expected behavior: [what a user or test should observe]
Acceptance checks:
1. [specific behavior]
2. [relevant test or manual check]
3. [error or edge case]
Constraints: [what must remain compatible or unchanged]
Before editing: inspect the relevant code and state the approach. Ask if a decision changes the public API, data model, auth, or deployment.
When done: report changed files, commands run with results, a preview or reproduction path, unresolved risks, and the branch or PR. Do not claim a check passed unless you ran it.Filled example: settings form
A small request with visible acceptance criteria and a clear review path.
Goal: Save a display name from the account settings page.
Project area: web app settings form and existing profile API.
Evidence: clicking Save currently shows a spinner, then the old name returns after refresh.
Expected behavior: the new name appears in the header and remains after refresh.
Acceptance checks:
1. A valid name saves and shows a success state.
2. An empty name shows a useful error and does not send a save request.
3. Run the relevant form and API tests; preview at desktop and mobile widths.
Constraints: do not change the profile API shape or authentication flow.
Before editing: inspect the current form and API call; explain the likely failure.
When done: show the changed files, test commands/results, preview steps, and any unresolved issue.Frequently asked questions
Should I paste the whole codebase into the prompt?
Usually no. Point the agent to the relevant area and let it inspect files as needed. Include exact error output when it is needed to reproduce the issue.
Can a non-coder use this brief?
Yes. Describe the observable result and how you will inspect it. Ask a qualified reviewer to verify production-sensitive changes you cannot assess.