Last reviewed: 2026-06-21
Direct answer
A coding agent pull request should include change scope notes before the PR is opened. The notes should tell the reviewer what changed, which repository instructions shaped the work, what files or behaviors were intentionally left untouched, what checks were run, and what deserves the first human look.
GitHub describes pull requests as the workflow for proposing, reviewing, and merging code changes. That makes the PR description the right place to reduce review ambiguity before comments start piling up. A coding agent can produce a large, technically valid diff that is still hard to review if the reviewer cannot tell why each area changed. Change scope notes solve that problem by turning the branch into a reviewable story: this was the requested behavior, these were the boundaries, these checks were observed, and these questions remain open.
Repository instruction systems make this more important, not less. Codex documents repository instruction files, GitHub documents repository custom instructions for Copilot, and Claude Code documents project memory for carrying project-specific context. Those sources can guide the agent before it edits, but the reviewer should not have to infer how they affected the final change. A useful scope note names the instruction sources that mattered and explains their effect in plain language.
Use a short scope note when the agent modifies code, configuration, tests, documentation, generated assets, permissions, dependencies, or workflow files. The note does not need to restate the diff. It should make the diff easier to inspect.
A practical workflow:
- Setup assumptions: the agent worked on a dedicated branch, repository guidance was available before edits began, and the reviewer can compare the branch against the intended base branch.
- Happy-path request plan: ask the agent to produce a short change scope note with changed areas, files touched, checks run, known omissions, and reviewer focus areas.
- Error-path check: if the note claims broad cleanup, hidden refactors, or test coverage that is not visible in the diff or command output, send it back for a narrower rewrite.
- Minimum assertions: the note names the main behavior changed, lists important files or directories, identifies instruction files consulted, records checks with pass or fail status, and separates facts from recommendations.
- Pass/fail logging fields: branch name, PR title, scope summary, files reviewed, checks run, reviewer risks, follow-up owner, and decision.
- What not to assert: do not claim production safety, full test coverage, complete security review, exact tool behavior, or successful deployment unless those facts are directly verified.
Sanitized log-record template:
branch: feature/example-change
pr_title: Example scoped agent change
scope_summary: Placeholder summary of changed behavior
instructions_checked: AGENTS.md, repository instructions, project memory
checks_run: placeholder-check --mode review
check_result: pass|fail|not_run
review_focus: files, tests, edge cases
known_omissions: placeholder omissions
follow_up_owner: reviewer-or-author
merge_decision: pending|approved|changes_requested
For related review practice, see How to Hand Off Coding Agent Pull Requests for Review and How to Produce Reviewable Diffs From Coding Agent Sessions .
Who this is for
This guide is for engineers, maintainers, and technical leads who let coding agents prepare pull requests and need a repeatable handoff that reviewers can trust. It is especially useful when a repository has standing rules, custom instructions, project memory, or task briefs that may influence the agent’s choices.
It is not a replacement for code review. It is a review aid that keeps the agent from burying scope decisions inside a large diff. A reviewer still needs to inspect the changed files, read the tests, challenge assumptions, and decide whether the branch should merge.
The workflow also helps solo developers. When you return to an agent-authored branch after a few hours, the scope note gives you a quick way to remember what the session tried to do and what it deliberately avoided. That is especially helpful when several small agent runs touch the same area over time.
Key takeaways
- Put the scope note in the PR description or first review comment before asking for review.
- Describe the changed behavior, not only the files touched.
- Name the instruction sources that mattered, but do not paste long instruction files into the PR.
- Separate completed checks from checks the reviewer still needs to run.
- Call out intentional non-changes so reviewers can spot accidental overreach.
- Treat missing logs, missing source pages, and unavailable local checks as open questions.
- Avoid broad claims such as complete validation, production readiness, or security approval unless the evidence is present.
Sources checked
- GitHub pull requests documentation - accessed 2026-06-21; purpose: verify pull request review and collaboration boundaries.
- OpenAI Codex AGENTS.md guidance - accessed 2026-06-21; purpose: verify repository instruction-file context for coding agents.
- GitHub Copilot repository instructions documentation - accessed 2026-06-21; purpose: verify repository instruction guidance.
- Claude Code memory documentation - accessed 2026-06-21; purpose: verify project memory and instruction-file context for agent workflows.
Contract details to verify
| Area | What to verify | Source URL | Accessed | Safe candidate wording |
|---|---|---|---|---|
| Pull request review surface | A PR is the place where proposed branch changes are compared, reviewed, discussed, and merged. | https://docs.github.com/en/pull-requests | 2026-06-21 | “Use the PR description or first review comment to make the agent’s change scope easy to inspect.” |
| Repository instruction source | AGENTS.md is a documented way to give Codex repository guidance. | https://github.com/openai/codex/blob/main/docs/agents_md.md | 2026-06-21 | “Mention the repository instructions that shaped the agent’s work.” |
| GitHub Copilot instruction source | GitHub documents repository custom instructions for Copilot-assisted work. | https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions | 2026-06-21 | “If repository custom instructions were used, summarize the relevant effect on the change.” |
| Claude project context | Claude Code documents project memory for carrying project-specific context. | https://code.claude.com/docs/en/memory | 2026-06-21 | “If project memory affected the work, identify the decision it influenced.” |
| Scope-note evidence | The source docs support PR review and instruction context, but not project-specific test results. | https://docs.github.com/en/pull-requests | 2026-06-21 | “Record checks as observed outcomes, not assumptions.” |
Failure modes
Evidence gaps are the most common failure. The agent may say a check passed without showing the command, or it may summarize a source it could not actually inspect. The safe response is to keep the note factual: name what was observed, name what was not observed, and keep the decision pending until the missing evidence is available.
Scope drift is the second failure. A small bug fix becomes formatting cleanup, dependency churn, or unrelated refactoring. The note should make drift visible by listing intentional non-changes. If the branch includes unrelated edits, split them or explain why they are required for the requested behavior.
Environment mismatch is another problem. A local check can use different versions, credentials, feature flags, or runtime settings than the path reviewers care about. The scope note should not convert a local result into a broader guarantee. It should say where the check ran and what it did not prove.
Weak handoffs also slow teams down. A note that says “fixed and tested” without changed files, command names, results, and remaining uncertainty makes the next reviewer repeat the investigation. A better note gives the reviewer a compact map and leaves judgment where it belongs.
Finally, instruction overreach can hide inside agent work. Repository guidance can tell the agent how to behave, but it should not justify unrelated edits. If an instruction affected the branch, the note should connect it to a concrete change or boundary.
Reader next step
Before opening the next agent-authored PR, ask for a scope note with four sections: changed behavior, boundaries, checks, and reviewer focus. Compare that note with the diff before requesting review. If the note and diff disagree, fix the note or split the branch before involving reviewers.
If the branch is part of a larger agent workflow, pair this with Write Coding Agent Task Briefs That Produce Reviewable Changes so the request and the handoff use the same boundaries.
Use Agent Memory Review Before Long-Running Tasks as the next comparison point. Keep Agent Run Evidence Ledgers for Human Review nearby for setup and permission checks.
FAQ
What should a coding agent change scope note include?
Include the changed behavior, important files or directories, instructions that shaped the work, checks run, checks not run, intentional non-changes, and the reviewer’s first inspection points.
Where should the note go?
Put it in the PR description when the PR is opened. If the PR is already open, add it as a clear review comment and update the description when possible.
How long should it be?
Keep it short enough to scan in under a minute. A concise list is usually better than a narrative that repeats the diff.
Should the note include full command output?
No. Include the command name and result, then link or attach detailed output only when the reviewer needs it.
Should the note mention repository instructions?
Yes, when they affected the work. Name the relevant instruction source and summarize its practical effect. Do not paste a long instruction file into the PR.
What is the main failure mode?
The main failure mode is overclaiming. A scope note should not say that the change is fully safe, fully tested, or ready for production unless that conclusion is backed by visible review evidence.