How to Hand Off Work Between Coding Agent Sessions
Use a copyable handoff template to preserve decisions, unfinished work, test evidence and review boundaries between coding agent sessions.
A useful coding-agent handoff lets the next session verify where work stands and identify the next authorized action. Save the requested outcome, current revision, decisions, unfinished work and evidence in a durable place. Then have the next session check that record against the repository before editing.
Save a checkpoint before ending the session
Start with the working tree. Record the branch and commit, task-owned changes and unrelated changes that must be preserved. A commit identifies a revision; it does not explain the intent behind the work or prove it is ready to ship.
Separate three states: implemented, verified and accepted. Code can exist while tests remain unrun. Tests can pass while human review remains open. A deployment can succeed while the intended customer outcome still needs observation.
Copy this handoff template
Outcome requested:
Scope authorized / actions needing a decision:
Repository, branch and current commit:
Uncommitted task changes:
Unrelated changes to preserve:
Current decisions:
- Decision, owner, date and source
- Superseded choices and why they changed
Work state:
- Implemented:
- Still unfinished:
- Blockers and exact next recovery action:
Verification:
- Check, command, result, revision and timestamp
- Evidence link or retained artifact
- Checks not run and why
Review and release:
- Who reviewed what revision or evidence
- Required review still outstanding
- Deployment state and how it was observed
Next bounded action:
Acceptance criteria for that action:
Related notes and source links:
Store credentials in the appropriate secret store, never in this record. Link protected evidence only where the next reader has appropriate access. If a dashboard can change, retain a dated capture when authorized and useful.
Example: a fix that is not yet delivered
This is an illustrative handoff, not a customer result:
Outcome: stop a settings form from submitting twice. Implementation: the submit button disables while the request is pending. Verification: the focused duplicate-submit test passed against the recorded commit. Not verified: the slow-network browser path. Review: no human approval yet. Next action: exercise that path, save the result and request review of the same revision.
This gives the next session a bounded job. “Fixed the form, all good” would hide the missing evidence and invite premature completion.
Resume with a read-only check
Ask the next agent to follow this prompt:
Read the handoff and its source links. Inspect the current repository state
and applicable project instructions. Identify changes since the handoff.
Separate observed facts from assumptions. Tell me what is implemented,
what was verified, what remains unfinished and which approvals are missing.
Name the next action within the existing authorization. If the record and
the repository disagree, report the discrepancy before relying on either.
Do not make the agent replay every old conversation. Preserve the original sources, but retrieve the small set of current decisions and evidence relevant to the task. Use Notes to keep reusable knowledge focused and revisable.
Make the handoff a workflow
With files, keep the entry point short and link to maintained task and decision records. With a shared service, verify that a fresh session retrieves the same records and can distinguish a historical decision from its replacement. Neither storage choice eliminates the need to inspect live code and test results.
In the AIMake workflow, the harness prepares work with current project context, records evidence and closes the session with a factual outcome and follow-ups. Closing a session does not automatically accept the task or prove delivery. The harness still performs execution and reasoning; a human makes required review decisions.
Compare Markdown and shared memory before adding infrastructure. If continuity across teammates or harnesses is the missing piece, use the project-memory evaluation checklist and inspect AIMake’s plans.
Put your context to work.
Keep your project’s decisions, next steps and proof together as your agents work.
Explore the agent workflow →