Last reviewed: 2026-05-21
Direct answer
A good coding agent task brief is short, explicit, and testable. It tells the agent where the repository rules live, what files or features are in scope, what must not change, which checks prove the work, and how the result should be handed to a reviewer.
Use the brief to separate intent from implementation. The human should define the outcome, constraints, and acceptance criteria. The agent can then inspect the code, choose the smallest safe change, run checks, and explain what changed. This is different from asking the agent to “make the feature better.” A reviewable brief describes what a reviewer should be able to see in the diff, in the running behavior, and in the handoff note.
A reviewable task brief usually has seven parts:
- Goal: the user-visible change or bug fix.
- Repository context: the instruction files or project memory the agent must follow.
- Scope: files, modules, commands, and boundaries that are allowed or off limits.
- Acceptance criteria: observable behavior that must be true after the change.
- Verification plan: commands, smoke tests, and failure cases to run.
- Handoff format: what the agent should summarize for review.
- Non-goals: tempting refactors or unrelated cleanup to avoid.
If you are still building your repository instruction layer, start with How to Write Repository Instructions for Coding Agents and then use this article to turn those standing rules into one task at a time.
A compact task brief can look like this:
Goal:
Fix the settings save flow so a changed notification preference persists after reload.
Context to read first:
- Repository instruction file at the project root.
- Existing settings page implementation and tests.
Scope:
- Allowed: settings UI, settings API client, related tests.
- Do not change authentication, database schema, unrelated preferences, or build tooling.
Acceptance criteria:
- Saving a changed notification preference shows success.
- Reloading the settings page shows the saved value.
- A failed save displays a recoverable error and does not show success.
Verification:
- Run the relevant unit or integration tests.
- Run one manual happy-path check and one failed-save check if the app can be started locally.
Handoff:
- Summarize changed files, checks run, failures encountered, and any remaining risk.
For broader release checks, see AI Coding Agent Setup, Security, and Model Routing .
Who this is for
This guide is for developers, engineering managers, and technical operators who assign work to coding agents and want outputs that are easy to review. It is especially useful when agents work in repositories with standing instruction files, project memory, automated tests, and pull request review.
It is not a promise that every coding agent uses identical instruction precedence or execution behavior. Repository instructions, project memory, task prompts, and pull request workflows vary by tool. Verify the exact behavior in the linked product documentation before depending on a specific feature.
Key takeaways
- Put durable repository rules in the tool-supported instruction or memory mechanism, then keep the task brief focused on the current change.
- Write acceptance criteria as observable outcomes, not vague preferences.
- Include at least one happy-path check and one error-path check when the change has runtime behavior.
- Tell the agent what not to touch so it avoids broad refactors that make review harder.
- Ask for a reviewer-friendly handoff: changed files, checks run, known failures, and remaining risk.
- Use pull requests or equivalent code review flow for anything that changes production code.
How to write the brief
Start with the outcome, not the implementation. A useful goal says what should be true for the user, operator, or reviewer after the task is complete. “Fix settings persistence” is better than “look at settings bugs,” and “saving a changed notification preference persists after reload” is better still.
Next, point the agent to standing context. Many coding-agent tools support repository instructions, custom instructions, or project memory. Those mechanisms are useful for durable rules such as test commands, style conventions, security boundaries, generated-file policy, and preferred handoff format. The task brief should reference that standing context rather than copy it into every request.
Then set the work boundary. Name the feature area, modules, or files that are likely in scope. Also name the areas that should not change. Non-goals are not bureaucracy; they protect review quality. If a task is supposed to repair one save flow, the agent should not also update authentication, replace a dependency, rename unrelated components, and reformat half the repository.
Finally, make the verification plan realistic. Ask for the most relevant automated check that exists, then add one manual happy-path check and one realistic failure-path check when the task changes runtime behavior. If the requested check cannot run in the agent’s environment, the handoff should say so plainly and list the closest substitute.
Smoke-test workflow
Use this workflow when the task brief asks a coding agent to change behavior rather than only edit documentation.
Setup assumptions:
- The repository already has a documented way to install dependencies and run tests.
- The agent can read the repository instruction file or project memory supported by the selected tool.
- The human has identified the feature area and any files that are out of scope.
Happy-path request plan:
- Start from a clean branch or isolated workspace.
- Read the repository instructions and the task brief.
- Make the smallest code change that satisfies the acceptance criteria.
- Run the narrowest relevant automated test first.
- If a local app can run, perform one happy-path action that proves the changed behavior.
Error-path check:
- Trigger the main expected failure condition, such as invalid input, a failed save, or a missing dependency.
- Confirm that the user-visible error is safe and that success is not falsely reported.
- Confirm that the failed action does not corrupt nearby state.
Minimum assertions:
- The changed behavior matches the acceptance criteria.
- The related test or smoke check passes.
- The error path fails safely.
- No unrelated files were changed without explanation.
- The handoff lists every check that was run.
Pass/fail logging fields:
run_id: example-run-id
branch_or_workspace: example-branch
brief_title: example-task-title
agent_tool: example-tool-name
repository_rules_read: yes-or-no
happy_path_check: placeholder-description
happy_path_result: pass-or-fail
error_path_check: placeholder-description
error_path_result: pass-or-fail
automated_checks: placeholder-command-list
changed_files_summary: placeholder-summary
review_notes: placeholder-notes
remaining_risk: placeholder-risk
The smoke test must not assert exact model behavior, hidden reasoning quality, platform uptime, pricing, quota, or account-specific limits unless those details are verified separately in the relevant product documentation or account console.
Failure modes
A task brief can look complete and still produce a change that is hard to review. Watch for these operational failure modes before assigning the work.
First, the brief may omit the repository instruction source. If the agent does not know which standing rules to read, it may follow only the immediate prompt and miss local conventions about tests, security boundaries, generated files, or review format. The fix is to point to the repository instruction or memory mechanism supported by the tool, while keeping the task brief focused on the current outcome.
Second, acceptance criteria may describe intent instead of observable behavior. “Improve the onboarding flow” invites a broad diff and subjective review. “A new user can complete the three-step onboarding form, see a confirmation screen, and resume after refresh” gives the agent and reviewer concrete evidence to check.
Third, the scope may be too wide. If a small bug fix allows changes to authentication, database schema, styling, dependency versions, and tests at the same time, the reviewer must audit unrelated risk. A better brief names the allowed feature area and explicitly lists non-goals. If the agent finds that an off-limits area is truly blocking the work, it should stop or explain the blocker rather than silently expanding scope.
Fourth, the verification plan may cover only the happy path. Many production regressions appear when a save fails, a network request times out, validation rejects input, or an existing setting is missing. For behavior changes, include at least one realistic failure path and say what safe failure looks like. The expected result can be simple: no false success message, no corrupted state, and a recoverable error for the user.
Fifth, the brief may ask for tests that do not exist or cannot run in the agent environment. That does not mean the task is impossible, but it must change the handoff. Ask the agent to run the closest available check, state which requested check could not run, and describe the remaining risk. A silent “tests not run” gap is much harder to review than an explicit limitation.
Sixth, the handoff may be too thin. A reviewer should not have to infer the agent’s path from the diff alone. Require a short summary of changed files, checks run, failures encountered, manual smoke tests, and remaining risk. For teams using pull requests, align that handoff with the review process described in your repository and collaboration workflow. For related handoff patterns, see Test Repair and Pull Request Workflow for Coding Agents .
Seventh, parallel work can collide. Two agents editing nearby files may each pass local checks but create merge conflicts or inconsistent behavior together. If the repository uses isolated branches or workspaces, make the branch, worktree, or ownership boundary part of the brief. The companion guide on Repository Context and Parallel Agent Workflows is useful when multiple agents are active in the same codebase.
Eighth, the brief may mix product intent with account-specific assumptions. A task can safely say “handle a failed save without showing success.” It should not assume a vendor quota, model limit, exact uptime behavior, or hidden platform feature unless the team has verified that detail in current documentation or its own account console.
Sources checked
- OpenAI Codex AGENTS.md guidance - accessed 2026-05-21; purpose: verify repository instruction-file concepts for Codex-style coding agent work.
- GitHub Copilot repository custom instructions - accessed 2026-05-21; purpose: verify repository-level instruction concepts for Copilot on GitHub.
- Claude Code memory documentation - accessed 2026-05-21; purpose: verify project memory and instruction context concepts for Claude Code workflows.
- GitHub pull request documentation - accessed 2026-05-21; purpose: verify pull request review and collaboration framing.
Contract details to verify
| Area | What to verify | Source URL | Accessed | Safe candidate wording |
|---|---|---|---|---|
| Repository instruction files | Confirm the supported filename, location, and scope rules for the coding agent being used. | https://github.com/openai/codex/blob/main/docs/agents_md.md | 2026-05-21 | “Place durable repository rules in the instruction mechanism supported by your coding agent.” |
| Repository custom instructions | Confirm how repository instructions are added and maintained for Copilot on GitHub. | https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions | 2026-05-21 | “Repository-level instructions can help keep repeated guidance out of each task brief.” |
| Project memory | Confirm how Claude Code loads and manages memory for project context. | https://code.claude.com/docs/en/memory | 2026-05-21 | “Project memory can carry standing guidance, but the task brief should still define the current outcome.” |
| Review handoff | Confirm the pull request flow and review expectations used by the team. | https://docs.github.com/en/pull-requests | 2026-05-21 | “Use a pull request or comparable review flow when an agent changes code.” |
FAQ
How long should a coding agent task brief be?
Long enough to define the outcome, constraints, acceptance criteria, and verification plan. If the brief repeats standing repository rules, move those rules into the tool-supported instruction or memory mechanism and reference them from the task.
Should I tell the agent exactly which files to edit?
Only when file boundaries matter. It is usually better to name the feature area, list files that are off limits, and let the agent inspect the implementation. For risky code, give tighter boundaries.
What makes acceptance criteria reviewable?
Reviewable acceptance criteria describe behavior a person or test can observe. “Improve the settings page” is weak. “Saving a changed notification preference persists after reload” is stronger.
Should every task brief require tests?
For code changes, require the most relevant automated check that exists. If no suitable test exists, ask the agent to explain that gap and run a small manual smoke check when possible.
How do I prevent unrelated refactors?
Add a non-goals section. Name the files, modules, or behaviors that must not change unless the agent finds a blocker and explains it in the handoff.
Reader next step
Turn the next coding-agent request into a one-page task brief. Include the goal, repository context, allowed scope, non-goals, acceptance criteria, verification plan, and reviewer handoff before the agent starts.
Use AI Coding Agent Setup, Security, and Model Routing as the next comparison point, keep Repository Context and Parallel Agent Workflows nearby for setup and permission checks, and compare the final handoff against Test Repair and Pull Request Workflow for Coding Agents before asking a reviewer to inspect the change.