How to preserve context across AI coding agents

What context should survive a coding-agent switch?

The successor needs more than a summary of the conversation. It needs the intended outcome, the exact repository state, decisions already made, commands already run, evidence from tests or logs, unresolved risks, and one bounded next action. Preserve pointers to the canonical files instead of copying large source files into prose.

• Objective and acceptance criteria.
• Branch, commit, worktree, and relevant uncommitted changes.
• Files changed and files intentionally left untouched.
• Decisions, rejected alternatives, and reasons.
• Commands run with material results, including failures.
• Known risks, missing verification, and access constraints.
• The next command or edit and the actor expected to perform it.

How are instruction files different from a handoff?

Instruction files describe durable repository behavior; a handoff describes the changing state of one interrupted task. Codex discovers layered AGENTS.md files, Claude Code uses CLAUDE.md project memory, Gemini CLI loads hierarchical GEMINI.md context, and Cursor uses project rules while its CLI can also read AGENTS.md and CLAUDE.md. Put stable commands and conventions in those files. Do not rewrite them for every task.

Stable repository layer
  AGENTS.md / CLAUDE.md / GEMINI.md / .cursor/rules
  - architecture boundaries
  - coding conventions
  - build, lint, and test commands
  - safety and review expectations

Changing continuation layer
  HANDOFF.md or a versioned Handover record
  - objective and current state
  - decisions and evidence
  - exact Git state
  - unresolved risks
  - next action and owner

What is the minimum repository handoff workflow?

Before switching agents, make the repository state inspectable, update the handoff record, and run the smallest relevant verification. The receiving agent should independently inspect Git state and active instructions before acting. It should not assume the handoff is newer than the checkout.

# Sender
git status --short
git diff --stat
git rev-parse --short HEAD
npm test

# Update HANDOFF.md with the results, then publish the work package
handover publish . --title "Continue checkout reliability fix"

# Successor
handover search "checkout reliability"
handover pull <slug-or-url> --out ./continued-work
cd ./continued-work
git status --short
git log -1 --oneline

What should the successor verify before editing?

The successor should compare the handoff's declared commit and branch with the actual checkout, read the applicable nested instruction files, inspect changed files, reproduce one meaningful result, and check for open review comments. If evidence is stale or the expected revision changed, it should stop and refresh the record instead of writing over concurrent work.

• The repository and working directory are the intended ones.
• The branch, commit, and worktree match the handoff.
• No newer revision or unresolved comment changes the next action.
• Secrets, credentials, generated files, and local-only state were not copied.
• The stated failure or passing test can still be reproduced.
• The proposed next edit respects the nearest instruction file.

When is HANDOFF.md enough?

A committed HANDOFF.md is usually enough for one repository, one visibility boundary, one writer at a time, and a workflow whose evidence already lives in Git. Add a shared handover when work spans machines or repositories, includes files outside Git, needs authenticated authorship, carries human review, has parallel actors, or must remain searchable after branches are deleted.

How should coding agents use Handover through MCP?

Connect each host to the same Handover workspace, then have the sender publish a checkpoint and the successor search, read the exact current revision, retrieve artifacts and open annotations, and continue with the expected revision identifier. The agent identity comes from its authenticated credential; it should never claim authorship through tool input.

Sender
  1. handover.whoami
  2. handover.create or handover.continue
  3. attach HANDOFF.md, test output, and relevant artifacts

Successor
  1. handover.whoami
  2. handover.search
  3. read the current revision and open annotations
  4. verify Git and test state locally
  5. continue with expectedRevisionId

What should never be placed in a handoff?

Do not publish reusable credentials, private keys, raw environment files, unnecessary personal data, hidden chain-of-thought, or large generated directories. Record the result and the evidence needed to verify it, not every token produced while reaching it. Keep organization access explicit and use named, scoped service credentials for unattended agents.