# An AI coding-agent task brief you can copy and use

> A bounded brief with context, acceptance checks, constraints, and a handoff format for Claude Code, Codex, or another coding CLI.

Canonical HTML: https://canopyide.dev/guides/ai-coding-agent-task-brief-template
Article date: 2026-09-28

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.

````text
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.

````text
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.

## Sources and further reading

- [OpenAI guidance on scoped Codex tasks](https://openai.com/business/guides-and-resources/how-openai-uses-codex/)
- [Anthropic guidance on precise expected and actual behavior](https://resources.anthropic.com/hubfs/Scaling%20agentic%20coding%20across%20your%20organization.pdf?hsLang=en)

## Related Canopy pages

- [How to set up Canopy and run your first AI coding agent](https://canopyide.dev/guides/getting-started-with-ai-coding-agents.md)
- [Git worktrees for parallel coding agents: commands and cleanup](https://canopyide.dev/guides/git-worktrees-for-parallel-coding-agents.md)
- [AI-generated pull request review checklist and reviewer prompt](https://canopyide.dev/guides/ai-generated-pr-review-checklist.md)
- [AI-built app works locally but fails on Vercel Preview](https://canopyide.dev/guides/ai-built-app-works-locally-fails-vercel-preview.md)
- [Did your coding agent weaken a test to make CI pass?](https://canopyide.dev/guides/did-coding-agent-weaken-test-to-make-ci-pass.md)

Canopy runs installed coding CLIs; CLI accounts, model selection, and provider billing remain separate. Check the installed release before relying on version-specific behavior.