Last reviewed: 2026-06-17.
Direct answer
Coding agent repository handoff notes should let the next reviewer or agent answer five questions without reconstructing the whole session: what changed, why it changed, where the work is isolated, which checks ran, and what still needs human judgment. A good handoff connects repository instructions, branch or worktree state, pull request review context, and project memory into one short record.
Use the handoff as a working note, not a release note. It should name the active branch or worktree, summarize the intended change, list the files or areas touched, capture the verification commands and outcomes, and call out unresolved decisions. For related preparation patterns, see Write Coding Agent Task Briefs That Produce Reviewable Changes .
Who this is for
This guide is for engineers, tech leads, and operators who run coding agents across pull requests, worktrees, or longer repository tasks. It is especially useful when an agent session may be resumed by a different tool, reviewed by a teammate, or split across multiple isolated working directories.
Key takeaways
- Put repository rules first: link or name the instruction source the agent followed before describing the change.
- Record isolation state: branch name, worktree path, base branch, and any files intentionally left untouched.
- Separate facts from requests: completed checks belong in one list, open questions in another.
- Keep review evidence compact: include command names, pass or fail result, and the next action for each failure.
- Avoid claims the handoff cannot prove, such as final merge readiness, production safety, or performance impact unless those were directly verified.
Smoke-test workflow
Setup assumptions: the repository has a documented instruction file or project memory source, work is isolated in a branch or worktree, and the operator can inspect the current diff and test output.
Happy-path request plan:
- Ask the agent to produce a handoff note after completing a scoped repository task.
- Require the note to include the instruction source, branch or worktree state, touched areas, verification commands, results, unresolved decisions, and suggested reviewer focus.
- Compare the note against the current diff, pull request description, and any project memory file that was used.
Error-path check: intentionally remove one required item, such as the failed check summary or worktree path, and confirm the handoff is marked incomplete before review continues.
Minimum assertions:
- The handoff identifies the active branch or worktree.
- The handoff names the repository instruction or memory source used.
- The handoff lists checks that actually ran and their result.
- The handoff separates completed work from unresolved decisions.
- The handoff does not include credentials, private tokens, or unverified production claims.
Pass/fail logging fields:
handoff_id: "handoff-YYYYMMDD-placeholder"
repository_area: "placeholder-module-or-service"
branch_or_worktree: "placeholder-branch-or-path"
instruction_source_checked: "yes-or-no"
diff_summary_present: "yes-or-no"
checks_recorded: "yes-or-no"
unresolved_decisions_present: "yes-or-no"
reviewer_focus_present: "yes-or-no"
result: "pass-or-fail"
next_action: "placeholder-next-step"
What not to assert: do not claim the change is merge-ready, deployable, secure, or performance-neutral unless separate review and verification evidence supports those claims.
Failure modes
- Evidence gap: the agent cannot inspect the failing log, source page, pull request, or local command output. The safe action is to stop and record the missing evidence instead of guessing.
- Scope drift: the agent edits files that are not connected to the observed failure. Keep the repair tied to the failing signal and leave unrelated cleanup for a separate task.
- Environment mismatch: the local check uses different versions, credentials, feature flags, or runtime settings than the hosted path. Record the mismatch before treating the result as proof.
- Unreviewed fallback: the agent changes models, endpoints, permissions, or retry behavior to make a run pass without preserving the review boundary. Treat access and provider failures as operational blockers, not topic failures.
- Weak handoff: the final note says the issue is fixed but omits the command, result, changed files, and remaining uncertainty. That makes the next operator repeat the investigation.
Sources checked
- OpenAI Codex AGENTS.md guidance - accessed 2026-06-17; purpose: verify repository instruction-file context for coding agents.
- GitHub pull requests documentation - accessed 2026-06-17; purpose: verify pull request review and collaboration boundaries.
- Git worktree documentation - accessed 2026-06-17; purpose: verify parallel worktree isolation commands and constraints.
- Claude Code memory documentation - accessed 2026-06-17; 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 |
|---|---|---|---|---|
| Repository instructions | Whether the agent run followed the applicable repository instruction file or project memory source. | https://github.com/openai/codex/blob/main/docs/agents_md.md | 2026-06-17 | “Name the repository instruction source used for the run.” |
| Pull request handoff | Whether the handoff gives reviewers enough branch, review, and change context. | https://docs.github.com/en/pull-requests | 2026-06-17 | “Connect the handoff to the pull request review path.” |
| Worktree isolation | Whether the handoff records the worktree or branch used for isolated changes. | https://git-scm.com/docs/git-worktree | 2026-06-17 | “Record the worktree path or branch when isolation matters.” |
| Project memory | Whether persistent project context was consulted or updated according to the tool’s documented memory behavior. | https://code.claude.com/docs/en/memory | 2026-06-17 | “State which project memory or instruction source shaped the run.” |
| Verification evidence | Whether completed checks and unresolved failures are clearly separated. | https://docs.github.com/en/pull-requests | 2026-06-17 | “List checks run, results observed, and the next action for failures.” |
Reader next step
Compare the workflow against Start with CometAPI .
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
How long should a coding agent handoff note be?
Keep it short enough for review, but complete enough to preserve state. A useful note usually covers scope, isolation, changed areas, checks, unresolved decisions, and reviewer focus.
Should the handoff repeat the full diff?
No. It should summarize the diff and point reviewers to the branch, worktree, or pull request where the actual changes can be inspected.
Should agents update project memory during handoff?
Only when the tool and repository rules call for it. If memory was consulted or updated, the handoff should say so without copying sensitive details.
What is the biggest failure mode?
The common failure is mixing verified facts with assumptions. A handoff should make it obvious which checks passed, which checks failed, and which decisions still need a person.
Where should teams start?
Start with a small template that captures branch or worktree, scope, files touched, checks run, open risks, and reviewer focus. Expand it only when repeated reviews show missing information.