An AI coding agent is not done when it says “done.” It is done when the next person or agent can accept its work without reconstructing what changed, what was assumed, what was tested, and what remains uncertain.
That distinction calls for a handoff contract: a small, structured artifact that travels with every patch. It records scope, assumptions, evidence, integration state, residual risk, and the owner of the next acceptance decision. Better prompts can improve code generation. They cannot replace this transfer of responsibility.
Prompts solve generation, not acceptance
Teams often react to a weak agent result by adding another instruction: run tests, check edge cases, avoid unrelated files, explain the diff. These instructions can help. But they still describe what the sender should do; they do not define what the receiver must be able to verify.
That is why a handoff belongs inside a production software delivery workflow, where code, evidence, integration state, and acceptance travel as one object. A patch without that context may be locally correct and still be expensive to integrate.
DORA's analysis of 1,110 open-ended responses from Google software engineers found that time saved during initial creation was frequently reallocated to auditing, verification, and iteration. The study is qualitative evidence from a specific population, not a universal productivity benchmark. Still, it names a pattern many teams recognize: faster output can move work downstream instead of removing it.
The same DORA analysis reports a tension between higher AI adoption, greater throughput, and greater delivery instability. Its broader software-delivery metrics framework deliberately measures both throughput and instability. “The agent produced more code” therefore tells us very little about whether the system can safely absorb that code.
A useful definition of a valid handoff
A 2026 survey of agentic electronic design automation defines a valid handoff in terms of the recipient: the transferred artifact must satisfy the next stage's acceptance conditions and carry enough context, evidence, and provenance for that stage to proceed. The paper is about EDA, not general application development, but its handoff perspective gives software teams a useful design rule:
Validate the transfer from the receiver's side, not only the work from the sender's side.
That rule changes the completion question from “Did the agent follow the prompt?” to “Can the next consumer make an informed acceptance decision?”
The five parts of an agent handoff contract
1. Scope
Record the exact requirement, owned files, and forbidden files. “Implement authentication” is not a scope. “Add refresh-token rotation in these three modules without changing the public session schema” is.
Scope prevents two opposite failures: incomplete work hidden behind a broad completion claim, and unrequested changes that make review harder.
2. Assumptions
List the conditions the patch relies on: base commit, interface versions, environment, fixtures, feature flags, data shape, or ordering guarantees. An assumption is not an embarrassment; an invisible assumption is a defect waiting for integration.
3. Evidence
Include the exact checks that ran and the results that matter. “Tests pass” is too lossy. A useful receipt names the command, exit status, relevant case count, and any validation that was intentionally not run.
Evidence should be reproducible and proportional. A one-line configuration change rarely needs a full-system stress run. A persistence or concurrency change needs more than a type checker.
4. Integration state
Say whether the patch was tested alone, applied to the intended base, combined with adjacent work, and validated through the shared seam it changes. Local green and integrated green are different states.
This matters even more in production AI evaluation and monitoring systems, because prompt versions, evaluation results, drift signals, and rollback state must survive every model or workflow change. A locally successful prompt or evaluator is not yet an accepted production change.
5. Residual risk and acceptance owner
Name what remains unknown, the next consumer, and the decision that consumer owns. “No known risks” is credible only when the evidence supports it. Otherwise, state the boundary plainly: migration behavior was not exercised, browser compatibility remains unverified, or the adjacent branch has not landed.
The acceptance owner might be a human reviewer, an integration agent, a release gate, or an on-call engineer. The important part is that ownership is explicit.
The five fields that turn a completion message into an acceptance-ready handoff.
A copyable handoff format
The contract does not need a new platform. Start with a versioned YAML block in the pull request, task artifact, or agent output:
handoff_version: 1
work_item: AUTH-217
producer: coding-agent-session-42
base_commit: 8d31c2a
scope:
requirement: Rotate refresh tokens after every successful use
owned_paths:
- src/auth/refresh.ts
- tests/auth/refresh.test.ts
forbidden_paths:
- src/auth/session-schema.ts
assumptions:
- The token store provides compare-and-swap semantics
- Existing session payload fields remain stable
evidence:
- command: npm test -- tests/auth/refresh.test.ts
exit_status: 0
result: 12 passed
- command: npm run typecheck
exit_status: 0
integration_state:
applied_to_base: true
adjacent_changes_combined: false
shared_seam_verified: false
residual_risk:
- Concurrent refresh from two browser tabs was not exercised
acceptance:
owner: integration-agent
next_gate: Combine the session-store patch and run the auth integration suite
This format makes absence visible. If shared_seam_verified is false, the workflow does not have to guess whether anyone checked it. If a command is missing, the receiver can request the smallest useful check instead of rerunning everything.
“Agent done” and “handoff valid” are different states
Imagine two agents working in parallel. One changes a serializer. The other adds validation to its consumer. Both run focused tests, both report success, and both are truthful. When combined, the serializer emits a value that the new validator rejects.
Neither local report captures the failure because the failure exists in the transfer between the two pieces of work. A handoff contract exposes the missing state:
| Sender report | Receiver question |
|---|---|
| “My tests pass.” | Were adjacent patches combined? |
| “The interface is unchanged.” | Which interface version and invariants were checked? |
| “No conflicts.” | Was only textual conflict checked, or behavioral compatibility too? |
| “Ready to merge.” | Who owns acceptance, and which gate makes it true? |
The contract does not magically prevent the incompatibility. It prevents the workflow from mislabeling unintegrated work as accepted work.
Validate the contract from the next consumer's viewpoint
A useful receiver loop has four steps:
- Check completeness. Are all five parts present, or is an omission explicitly marked?
- Check claims against artifacts. Do the diff, base commit, and test receipts support the summary?
- Run the cheapest discriminating gate. Test the shared seam before rerunning an entire repository.
- Accept, return, or escalate. Record the decision and its reason instead of silently repairing the patch downstream.
That last step matters. If integrators repeatedly fix incomplete handoffs without returning the signal, the producing agent never receives a useful boundary and the organization hides the true cost of the workflow.
Start small
Do not begin by building a handoff service. Add the YAML block to one workflow where parallel agents touch a shared interface. Require only fields that change an acceptance decision. Track three outcomes for a few real tasks:
- how often the receiver had to reconstruct missing context;
- how often local green became integrated red;
- how long it took to reach an acceptance decision.
Then revise the contract when a missing field causes a real ambiguity. A handoff contract should become smaller and sharper over time, not grow into ceremonial paperwork.
Frequently asked questions
Is this just a pull request template?
It can live in a pull request, but it serves a broader role. A PR template is usually organized around human review. A handoff contract is a machine-readable transfer between any producer and the next acceptance stage, including agent-to-agent workflows before a PR exists.
Should the agent decide whether its own handoff is valid?
The agent can validate completeness and attach evidence. Final validity belongs to the receiver because only the receiver owns the next stage's acceptance conditions.
Does every task need all five parts?
Yes, but a field can be short. For a tiny documentation edit, integration state may be one sentence and residual risk may be “none identified.” Keeping the schema stable is useful; scaling the evidence to the risk keeps it practical.
The real unit of progress
Code generation is an activity. Accepted change is progress.
Once teams measure the transfer between those states, the next improvement is often not a longer prompt. It is a clearer contract at the boundary: what moved, what it depends on, what proves it, what remains unintegrated, and who can accept it next.
Top comments (0)