Skip to main content
After changing code, an AI coding agent should hand back a compact completion contract that connects the patch to the request: the exact revision, a map of the consequential changes, validation evidence, unresolved questions and risks, and the effect on maintained documentation. The handoff should help the team verify the work, not recount the agent’s session or certify the patch as safe. Last reviewed July 18, 2026. Maintained by the Plannotator project. For a small, reversible edit, those facts may fit in six lines. A cross-cutting authorization change may need an approved plan, migration output, screenshots, and rollout notes. Choose evidence based on the consequences of the change, not the amount of AI used to produce it.
An AI coding agent hands a team one versioned evidence folio containing the code diff, decision context, validation, risks, review artifact, and follow-up work.

​
What the patch and summary leave out

The Git diff is the implementation record. It does not say which request authorized the work, which paths the agent exercised, which assumptions remain unresolved, or whether a polished screenshot belongs to the current revision. A prose summary helps a reviewer get oriented, but it is still an interpretation of the patch. GitHub recommends that pull request authors provide the purpose, an overview, links to context, and guidance about where to begin reviewing. Authors should also review, build, and test their changes before requesting review. See GitHub’s guidance for making changes easier to review. GitHub and Codex already expose parts of this record. GitHub lets reviewers query a Copilot-created pull request’s session logs to ask what changed, what was validated, and why. OpenAI’s Codex reports citations, terminal logs, and test results. See GitHub’s pull request exploration guide and OpenAI’s introduction to Codex. Both vendors still instruct users to review agent-created code before integration. GitHub says to review Copilot’s pull requests thoroughly. Use the handoff as a stable index into the request, code, and evidence a reviewer needs to decide. The diff, CI results, and agent logs remain the source records.
Evidence topology

One index, six source records

Approved request

Intent and constraints

Exact revision

SHA, diff, change map

Validation

Checks and runtime proof

Review artifacts

UI, video, traces

Handoff index

Points to evidence

Risks and questions

What remains unresolved

Documentation

Maintained truth changed

The diff, CI results, artifacts, and approved request remain the source records.

​
The compact agent handoff contract

Use six required fields. Add conditional evidence only when it applies. Add these fields only when they apply:
  • Review artifacts: screenshots, recordings, HTML walkthroughs, traces, benchmark results, or migration evidence that make behavior inspectable. Explain which claim each artifact supports.
  • Data and rollout: schema changes, compatibility window, backfill, deployment order, feature flag, rollback trigger, and operator ownership.
  • Security and privacy: changed trust boundaries, permissions, secrets, customer data, threat assumptions, and the responsible reviewer.
  • Follow-up work: deferred cleanup or monitoring with an owner and a concrete issue, not vague “future improvements.”
Use this template:
Put the fields in a pull request template if that makes them easier to complete. The agent can populate them, but the person or team presenting the change for review owns their accuracy.

​
Make validation evidence specific and revision-bound

“Tests pass” is not useful evidence without scope. A reviewer needs to know whether the agent ran one targeted unit test, the repository’s complete test suite, a browser flow, or only a type-check. Record the command or named CI job and its result:
  • pnpm test --filter authorization: 42 passed;
  • pnpm typecheck: passed;
  • checkout browser flow at mobile and desktop widths: passed, screenshots attached;
  • production-like migration rehearsal: not run; staging database unavailable.
Tie that evidence to the handed-off SHA. GitHub status checks are reported against commits, and its Checks view can display results for different commits in the same pull request. See GitHub’s status-check documentation. When the agent pushes another commit, the code under review changes. The handoff and any manually produced evidence may need to change with it. A revision diff helps a returning reviewer isolate what moved since the last checkpoint instead of assuming an earlier test report or screenshot still applies. Do not paste every successful log into the pull request. Link to full CI output and surface the evidence that changes the decision. State plainly when a check failed, was skipped, or cannot reproduce the target environment.

​
Use artifacts to show behavior the diff cannot show

Visual and operational changes often need more than textual test output. A UI change may need before-and-after screenshots and a short recording. A parser change may need a table of difficult inputs and outputs. A data migration may need rehearsal counts, timing, and rejected-row samples. These code review artifacts provide evidence beside the patch. Claude Code, for example, can publish session artifacts such as pull request walkthroughs, system explainers, and release checklists. Anthropic describes them as pages built from the codebase, connected tools, and session context. See Anthropic’s Claude Code artifacts announcement. An artifact is not proof merely because it looks complete. Identify its source, revision, and supported claim. Reviewers must still inspect the underlying behavior and code. For format guidance, read When Should AI Coding Agents Produce HTML Instead of Markdown?.

​
Small-change fast path

Suppose an agent fixes an off-by-one error in pagination, changes one implementation file, and adds one regression test. No API contract, customer-visible workflow, or maintained architecture document changes. The handoff can stay compact:
Request: Fix issue #184: page 2 repeats the final item from page 1.
Revision: PR #219 at 71be993.
Changed: Corrected the cursor offset in pagination.ts; added the boundary case in pagination.test.ts.
Validated: Targeted test file, 18 passed; type-check passed.
Open questions / risks: None identified.
Documentation: None; the public behavior now matches the existing API documentation.
These six lines identify the request, code, and validation claim. A formal planning package or long session transcript would not help the reviewer decide whether to merge this fix.

​
Use the full handoff for a cross-cutting change

Now suppose a team replaces a synchronous customer-data export endpoint with a queued export service. The implementation touches the public API, a jobs table, a background worker, encrypted object storage, download authorization, the account UI, audit events, retention cleanup, and operator documentation. A useful handoff might say:
  • Request: Export-service plan version 6, approved by product, data, and security. The agent deviated from emailing export files after the security review required a short-lived authenticated download.
  • Revision: Pull request head c4a912e in the API repository plus 7b21d0a in the web repository.
  • Change map: Read the export state machine first, then the jobs migration, worker, object-storage adapter, download authorization, account UI, and retention cleanup.
  • Validation: Unit and integration suites passed; the migration was rehearsed against a sanitized production-shape snapshot; expired and cross-organization download links were rejected; the browser flow passed with screenshots attached. Queue-saturation testing was not run because the staging capacity was unavailable.
  • Open questions and risks: Download links expire after 24 hours. Rollback disables new export requests but allows already queued jobs to finish. Security review and an alert on failed retention cleanup remain required before launch.
  • Documentation: Updated PRODUCT.md with the customer-visible lifecycle, TECH.md with the storage and authorization boundaries, and the operator runbook with rollout, rollback, queue recovery, and retention steps.
Several teams must verify different claims and operate the export service, so the handoff needs more evidence. It remains a map, not an agent transcript. The project’s issue, plan, or review system records what was authorized; the handoff records what the agent produced and any deviations. Plannotator’s local plan review loop can help refine the plan before that external record is made. After merge, durable decisions should enter living codebase documentation. For the complete path from request through team decision, implementation evidence, and shipping, read How Teams Understand AI-Generated Code Before Shipping It.

​
What a handoff cannot establish

  • It is authored by the same agent that may have misunderstood the request or missed a failure. Treat its claims as review leads, not independent verification.
  • Passing tests demonstrate only the paths and assertions they cover. They do not prove the change satisfies the product decision.
  • A commit SHA identifies code, not every external dependency, service response, or mutable artifact used during validation.
  • Logs and artifacts can expose secrets or customer data. Redact and retain them according to the repository’s access rules.
  • A large handoff cannot rescue a pull request that is too broad to review. Split the implementation when reviewers cannot form a reliable mental model.
Anthropic’s long-running agent harnesses used structured updates alongside Git history so the next session could resume the work. A team handoff uses the same practice to prepare an implementation for review. See Anthropic’s long-running agent harness research.

​
Frequently asked questions

​
What should an AI coding agent include in a pull request?

Include the authorizing request, exact head revision, a change map, validation commands and results, unresolved questions and risks, and documentation impact. Add screenshots, HTML, migration evidence, rollout instructions, or security notes only when the change requires them.

​
How detailed should an AI coding agent handoff be?

Use the smallest handoff that lets another engineer verify the work without reconstructing the agent session. A local fix may need six short lines; a cross-service migration needs more evidence.

​
Should the agent include every command and log?

No. Include decision-relevant commands and results, note anything skipped or failing, and link to complete logs when useful. Large pasted logs hide signal and can leak sensitive data.

​
How can a reviewer verify an agent’s handoff?

Confirm the request and revision, inspect the diff in the suggested order, open the linked evidence, check that CI belongs to the current commit, and rerun consequential validation when appropriate. Resolve discrepancies against the code and executable behavior, not the agent’s prose.

​
Who owns the accuracy of an AI coding agent handoff?

The person or team delegating the change owns the handoff presented for review. The agent can draft and update it, but it should not certify its own work as correct or ready to merge.

​
Handoff readiness checklist

Before handoff, a reviewer should be able to answer three questions without reopening the private agent session:
  1. What exact request and revision am I reviewing?
  2. What evidence supports the agent’s claims, and what remains uncertain?
  3. Which durable documents and operating assumptions change if we merge it?
If any answer requires reopening the private session, the handoff is incomplete.

Review the returned code

Open the current local changes in Plannotator and compare the handoff with the actual diff and validation evidence.
Last modified on July 19, 2026