How do you hand context cleanly between AI coding sessions?

Write a handoff artifact before the session ends: current state, decisions made with their reasons, what was verified and what remains open, and the concrete next step. Store it in the repository - not in the chat - so the next session (or the next person) starts from recorded facts instead of a cold prompt. Persistent instruction files like CLAUDE.md carry the stable rules; the handoff carries the moving state.

What belongs in a handoff document?

Five things: where the work stands (done/in progress), decisions with reasoning ('chose X over Y because...'), verification status (which criteria passed, which were skipped), open questions the next session must not silently re-decide, and the exact next step. What does not belong: the whole history - a handoff is a state snapshot, not a transcript.

Why isn't compaction or a bigger context window enough?

Compaction summarizes - and summaries drop exactly the specifics that matter later: precise numbers, exact file paths, the reason a decision went one way. A larger window delays the problem without removing it, and neither survives the session ending. Files on disk survive both; that is the whole trick.

What is the difference between CLAUDE.md and a handoff note?

CLAUDE.md (and its equivalents in other tools) holds the stable truths: architecture, conventions, constraints - things every session should know. The handoff note holds the volatile state of the current work stream: progress, open criteria, next step. Mixing them bloats the stable file until nobody reads it; keep rules and state separate.

What has session handoff to do with verification?

Lost context is a verification risk, not just an inconvenience. When a new session cannot see what was already checked and what was left open, it builds confidently on unverified assumptions - and the open points from yesterday silently become the shipped defects of next week. A handoff that records verification status keeps the open items visible until they are closed.

Does this work with tools other than Claude Code?

Yes - the method is a file convention, not a tool feature. Any agent that can read repository files can consume a handoff note; Cursor, Copilot, and terminal agents all qualify. Tool-specific memory features are a bonus where they exist, but the portable artifact is what survives tool changes.

Method

AI Session Handoffs

Last updated: 2026-07-024 min read

An AI session handoff writes the state of the work into a persistent artifact before a coding session ends: progress, decisions with reasons, what was verified, what stays open, and the next step. Stored in the repository, it turns the next session’s cold start into a warm one – and keeps yesterday’s open verification points from becoming next week’s shipped defects.

Contents

Why sessions forget – and why that is a verification problem

Every AI coding session runs against a finite context window. When it fills, tools compact: earlier messages get summarized, and summaries drop exactly the specifics that matter later – exact values, precise paths, the reason behind a decision. End the session, and even the summary is gone.

The convenient framing is “lost productivity”. The more dangerous one: lost verification state. A fresh session that cannot see what was checked and what was deliberately deferred will re-decide silently and build on unverified assumptions – the same circularity problem that motivates the spec-vs-implementation check, stretched across time. Research on delegation contracts treats the persistent record of “what was asked, allowed, returned, and evidenced” as the foundation of reviewability – a handoff is that record at session scale.

The method: rules in one file, state in another

Keep stable truths in the instruction file. Architecture, conventions, constraints – CLAUDE.md and its equivalents are re-read from disk every session and survive compaction. Rules only; no work state.
Write the handoff before the session ends. State, decisions with reasons, verification status, open questions, next step – five sections, a screen or less.
Store it in the repository. A handoff.md next to the code (or per work stream) – versioned, diffable, readable by any tool and any human.
Start the next session from it. First instruction: read the handoff. The session begins from recorded facts, not from a reconstruction.
Close the loop.Items in “open” either get verified or stay listed – they never silently disappear.

handoff.md

Example – not real run data

STATE      rate-limit header work · 2 of 3 tasks done
           [done] Retry-After on 429 · [done] unit tests
           [in progress] CDN passthrough check

DECISIONS  header value = window rest, NOT fixed 60s
           (matches RFC 6585 guidance; discussed with mk)

VERIFIED   criteria 1,2,4 PASS (see soll-ist-check.md)
OPEN       criterion 3: header visible behind CDN – needs
           staging access · DO NOT assume it works

NEXT       run staging check, then close criterion 3
           and update the evidence report

Limits and typical mistakes

Transcript dumping. A handoff is a state snapshot, not a chat log. If it takes longer to read than the work took, nobody will read it.
Letting the model write it unreviewed. The session summarizing itself inherits its own blind spots – fine as a draft, but the human confirms what is actually open versus done.
Bloating the instruction file. Work state pasted into CLAUDE.md becomes stale rules that every future session obeys. Keep the volatile out of the stable.
Handoff without verification status. “Where I stopped” without “what is unverified” hands over the work but not the risk – the next session needs both.

Where Reality Graph fits

Reality Graph makes the handoff a by-product instead of a discipline: task state, boundaries, verification results, and open points live in the structured task and its evidence report – persistent in your environment, readable by the next session, the next tool, or the next colleague, as part of the verification loop.

A session handoff gives you

Warm starts from recorded facts, tool-independent
Decisions that survive with their reasons attached
Open verification points that stay visible until closed
A record any colleague can pick up mid-stream

It does not

Replace verification – it transports its status
Depend on any one tool's memory feature
Help as an unread transcript dump
Stay honest if the model writes it unreviewed

If these boundaries fit how your team wants to ship:

Get early access See how it works

FAQ

How do you hand context cleanly between AI coding sessions?: Write a handoff artifact before the session ends: current state, decisions made with their reasons, what was verified and what remains open, and the concrete next step. Store it in the repository - not in the chat - so the next session (or the next person) starts from recorded facts instead of a cold prompt. Persistent instruction files like CLAUDE.md carry the stable rules; the handoff carries the moving state.
What belongs in a handoff document?: Five things: where the work stands (done/in progress), decisions with reasoning ('chose X over Y because...'), verification status (which criteria passed, which were skipped), open questions the next session must not silently re-decide, and the exact next step. What does not belong: the whole history - a handoff is a state snapshot, not a transcript.
Why isn't compaction or a bigger context window enough?: Compaction summarizes - and summaries drop exactly the specifics that matter later: precise numbers, exact file paths, the reason a decision went one way. A larger window delays the problem without removing it, and neither survives the session ending. Files on disk survive both; that is the whole trick.
What is the difference between CLAUDE.md and a handoff note?: CLAUDE.md (and its equivalents in other tools) holds the stable truths: architecture, conventions, constraints - things every session should know. The handoff note holds the volatile state of the current work stream: progress, open criteria, next step. Mixing them bloats the stable file until nobody reads it; keep rules and state separate.
What has session handoff to do with verification?: Lost context is a verification risk, not just an inconvenience. When a new session cannot see what was already checked and what was left open, it builds confidently on unverified assumptions - and the open points from yesterday silently become the shipped defects of next week. A handoff that records verification status keeps the open items visible until they are closed.
Does this work with tools other than Claude Code?: Yes - the method is a file convention, not a tool feature. Any agent that can read repository files can consume a handoff note; Cursor, Copilot, and terminal agents all qualify. Tool-specific memory features are a bonus where they exist, but the portable artifact is what survives tool changes.

Keep reading

ConceptThe Verification Gap96% distrust AI code, only 48% always check it: all key numbers behind the verification gap from Sonar's 2026 survey - sourced, tabulated, and explained.ConceptThe AI Code Review BottleneckGeneration got cheap, reading did not: merged PRs nearly double while review time rises 91%. The mechanics of the new constraint, the measured numbers, and what actually relieves it.All articlesThe whole collection – 30 cited, dated guides on verifying AI-generated code.