A reliable AI coding agent handoff contains the current goal, verified state, exact changes, decision boundaries, failed paths, required checks, and the next safe action. It should be readable by Codex, Claude Code, Cursor, Copilot, or a human without depending on one tool's private chat history.

The handoff is not a meeting note. It is a restart interface.

The essential checklist

Outcome

  • What can the user do when this work is complete?
  • Which part is complete now?
  • Which part remains open?

Current state

  • Current branch and commit.
  • Relevant uncommitted files.
  • Runtime or deployment identity.
  • Exact post, task, migration, or release IDs.
  • Latest authoritative status.

Evidence

  • Commands that were actually run.
  • Tests, builds, or browser checks that passed.
  • Final artifact or public readback.
  • Known unverified conditions.

Decisions

  • Why the current path was selected.
  • Which alternatives were rejected.
  • Which product and data boundaries must remain.
  • Which decisions still require the user.

Failures

  • The exact failing step.
  • Error or observable mismatch.
  • Attempts already proven ineffective.
  • Whether an external write has a known or unknown outcome.

Next action

  • The first broken link to repair.
  • Authorized repository or service.
  • Completion evidence.
  • Stop conditions.

Use stable identities

Avoid phrases such as:

  • the latest deployment;
  • the new draft;
  • that test article;
  • the current task.

Replace them with a commit hash, deployment ID, post ID, version ID, URL, or issue number. A handoff becomes unsafe when the next session must infer which object matters.

Keep observations separate from conclusions

Write:

  • Observed: the lifecycle event is delivered, but the public page still shows the old title.
  • Inference: the consumer projection may not have activated.

The next agent can investigate the inference without treating it as truth.

Record what not to repeat

Failed paths save time only when they remain discoverable. Record the command or approach, the evidence that disproved it, and the condition under which it might become relevant again.

Do not write “didn't work.” Write enough for a new agent to recognize the same path before spending another hour on it.

Make the handoff tool-neutral

Repository files, tests, commits, URLs, and public contracts can be read by different agents. Private conversation summaries cannot always travel.

A developer asking what gets lost when switching agents named the same durable elements: codebase structure, conventions, architecture decisions, dead ends, and reasoning behind choices. The useful answer was to keep design notes, implementation checklists, and review feedback outside one session: discussion.

A copyable handoff

Goal

[User-visible result]

Verified current state

  • Repository/branch/commit:
  • Runtime/release:
  • Passing checks:
  • Final consumer evidence:

Changes made

  • Files or objects:
  • Behavior changed:
  • Behavior preserved:

Decisions

  • Selected path:
  • Rejected path:
  • Invariants:

Remaining gap

  • First broken link:
  • Evidence:
  • Risk:

Next safe action

  • Scope:
  • Verification:
  • Stop conditions:

Handoff quality test

Give the handoff to a fresh session and ask it to answer:

  • What is the user outcome?
  • What is true now?
  • What must not change?
  • What failed already?
  • What is the next action?
  • What proves completion?

If it must search the entire chat to answer, the handoff is incomplete. If it can answer but cannot verify the claims, evidence links are missing.

The core principle

A good handoff transfers responsibility without transferring confusion. It preserves verified project state and lets the next agent begin with action, not archaeology.