HANDOFF.md: handing work between AI coding sessions, and to people

Published 26 October 2026

A HANDOFF.md is a short file that an AI coding session — or a developer — writes before it stops, so that the next session or person can carry on without the conversation: the goal, what is done, what is half done, what was tried and failed, what to watch for, and the next step. It is temporary. The spec says what the software must do, the plan says how, CLAUDE.md or AGENTS.md says how to work in the repository; the handoff says where this piece of work stands right now. Below: why sessions need one, a template, an example, what goes where, what hospitals learned about handoffs, what the tools’ own documentation says, and handing AI-built work to people.

The developer’s intent lives ephemerally in a chat transcript; the generated code is voluminous and often opaque

— Paltenghi and Chandra, on what remains of AI-built software when the conversation ends (AfterVibe, 2026, preprint)

Why AI coding sessions need a handoff

A coding agent works inside a context window. When the window fills, the tool compacts the conversation into a summary or the session ends, and the next session starts with only what was written down. One developer’s description of the problem: “If the work requires multiple sessions, you need a way to hand off what one session learned to the next. Otherwise, every session starts from scratch” (PhotoStructure, 2026).

The same thing happens between people. A developer goes on holiday, an agency hands a project to the client’s team, a contractor leaves. In both cases the code survives and the reasons do not — unless someone wrote them down.

What the tools themselves say

None of the tools’ documentation names a file called HANDOFF.md; it is a convention, not a feature. But each tool describes the same problem, and most solve part of it.

Every session starts empty. Claude Code’s documentation: “Each Claude Code session begins with a fresh context window.” When the window fills, “It compacts the conversation into a summary. The summary keeps your requests and key code snippets, but detailed instructions from early in the conversation may be lost. Put persistent rules in CLAUDE.md rather than relying on conversation history” (Claude Code).

Compaction is a handoff the tool writes for itself. The prompt that OpenAI’s Codex uses to compact a conversation begins: “Create a handoff summary for another LLM that will resume the task”, and asks for the progress and decisions, the constraints, the next steps, and the references needed to continue (openai/codex). GitHub Copilot’s summary “captures the goals of the conversation, what was done, key technical details, important files, and planned next steps” — and “You can’t reverse a completed compaction” (GitHub). Gemini CLI’s /compress will “Replace the entire chat context with a summary” (Gemini CLI). A HANDOFF.md holds the same content, written where a person can read it and correct it.

A summary is not always enough. Anthropic’s engineers, on agents that work across many sessions: “However, compaction isn’t sufficient.” Their harness had the first session create “a claude-progress.txt file that keeps a log of what agents have done”, read at the start of every later session together with the git history (Anthropic, 2025). A later post calls it by name: “a structured handoff that carries the previous agent’s state and the next steps” (Anthropic, 2026). The same post notes that a newer model needed such resets less, so the author dropped them from that harness — the file matters most when the work outlives one session, one tool or one person.

What the tools keep, they keep out of the repository. Claude Code writes plans to ~/.claude/plans/ and deletes them after 30 days by default (Claude Code). Cursor: “Plans are saved by default in your home directory. Click “Save to workspace” to move it to your workspace for future reference, team sharing, and documentation” (Cursor). Codex’s own advice on its memories: “Treat memories as a helpful recall layer, not as the only source for rules that must always apply” (Codex). A teammate, or the same developer on another machine, sees none of it. A HANDOFF.md committed to the repository is what they do see.

Some fold the handoff into the plan. OpenAI’s guide to long-running Codex work keeps a plan with a progress section and a decision log, so that “it should always be possible to restart from only the ExecPlan and no other work” (OpenAI Cookbook). That works too, as long as the plan is kept current; the point is one file that is true now.

People are already doing it. GitHub’s code search estimated about 207,000 public files named HANDOFF.md in October 2026 — against about 944,000 CLAUDE.md files and 1.1 million AGENTS.md. In a sample of 489 handoff and handover files (search order, not random), 95% were first committed in 2026 or later and 57% named an AI tool or session. The sections they share — current state, what changed, next steps, known traps, how to verify — are the template above. Decisions (19%) and open questions (6%) were the sections most often missing.

One word, several meanings: in some tools’ documentation “handoff” means moving a running session between machines (Claude Code’s --teleport, the Codex app’s Handoff) or between agents in one chat. This page is about the file.

HANDOFF.md template

Keep it short, overwrite it rather than append to it, and commit it with the work it describes.

# HANDOFF: [task]
[date, time] - [who or which session]

Status: [on track / blocked / broken]

## Goal
[One sentence.]
Spec: [file], version [x].

## Done
- [what], [the commit or test that
  proves it]

## In progress
- [what], [state: where it stopped]

## Next
1. [the very next step]

## Tried and failed
- [what], because [why]

## Watch for
- If [this happens], then [do this]

## Open questions
- [question] - [who decides]

## Before you start
Read this file and [spec], say back
what you will do next, then start.

HANDOFF.md example

The customer portal from the spec-driven development example: an AI coding session is building version 2 of the payment reminder — reminders now go out for partly paid invoices too (FR-016, after change request CR-10). The context ran out after the first task:

# HANDOFF: FR-016 version 2
18 June, 17:40 - session 3

Status: on track

## Goal
Reminders for every invoice not paid
in full. Spec: specs/reminder.md,
version 2 (17 June).

## Done
- Task 1: selection uses "not paid in
  full" (commit 4f2a9c1); tests for
  cases 1-3 pass

## In progress
- Test for case 4 (partly paid):
  written, failing. Test data has no
  part payment yet; fixture half done
  in tests/fixtures/invoices.py

## Next
1. Finish the fixture, run case 4
2. Task 2 needs no change (checked)

## Tried and failed
- Marking partly paid invoices as
  "open": breaks the receipt email
  (FR-015, must not change)

## Watch for
- If the reminder job sends twice in
  a test, check the reminder record
  (task 2) before changing task 1

## Open questions
- Show the amount still due in the
  email? Finance lead. Task 3 waits.

## Before you start
Read this file and the spec, say back
what you will do next, then start.

Two lines in it do most of the work. “Tried and failed” stops the next session from repeating the attempt that broke FR-015 — the one thing a fresh session cannot know. And the open question is written as a question with an owner, so the next session does not answer it by itself: whether the reminder shows the amount due is the finance lead’s decision, and when it is made it goes into the spec as version 3, not into this file.

What goes where: HANDOFF.md, the spec, the plan, CLAUDE.md

The handoff points to the others; it does not copy them. A decision made in a session belongs in the decision log and, if it changes behaviour, in the spec — a handoff is overwritten, and so is anything that lived only there. More on the long-lived files in AGENTS.md vs CLAUDE.md vs spec.md, and on plans in plan mode vs spec-driven development.

Give the next session the current state, not the story of how it got there. In one 2026 study, of 100 cases where agents succeeded from a final spec, 35 failed on at least one history of revisions that ended in the same spec (SpecPath, preprint). The history is for people; the handoff is for the next reader who needs to act.

What hospitals learned about handoffs

Medicine has worked on handoffs — one clinician passing a patient to the next at the end of a shift — at least since 2006, when the US hospital accreditor, the Joint Commission, made them a national patient safety goal. The US Agency for Healthcare Research and Quality’s patient-safety primer: “The seminal I-PASS study demonstrated that in a teaching hospital setting, implementation of a standardized handoff bundle […] markedly reduced the incidence of preventable adverse events associated with handoffs” (AHRQ PSNet). The I-PASS format has five parts, and each has a place in a HANDOFF.md:

The last part is the one software handoffs leave out. In a hospital, the receiver restates the plan before taking over; asking the next session to do the same — “say back what you will do next” — catches a misread handoff before it becomes a wrong change. The Joint Commission does not prescribe a tool, but expects handoffs to include “illness assessment, patient summary, to-do action list, and contingency plans” (AHRQ PSNet).

Handing AI-built work to people

The second meaning of “Claude Code handover” is the client kind: an agency or a freelancer hands over a project built with an AI coding agent. Everything in the software handover document applies. Two things are harder.

The builder may understand less of the code. In a randomised study of developers learning a new library, “using AI assistance to complete tasks that involve this new library resulted in a reduction in the evaluation score by 17% or two grade points” (Shen and Tamkin, 2026). In a survey of 80 practitioners who build software agents, 82% agreed that “comprehension debt” accumulates — “code is accepted before developers can explain, modify, and maintain it safely” (Lyu et al., 2026, preprint). A developer handed a client’s AI-built app: “you have completely no clue what part of the code are written/designed properly with good foundation if previous developer didn’t test extensively and didn’t refactor continuously” (Hacker News, 2026).

The next developer may be fine — if they have what they need. In a preregistered experiment with 151 participants, developers who evolved code written with AI assistance showed “no significant differences in subsequent evolution with respect to completion time or code quality” (Borg et al., 2026). And the intent can be recovered: the AfterVibe study recovered specs from 72 recorded AI coding sessions and tested them by regenerating the code from the specs alone (Paltenghi and Chandra, 2026, preprint) — which works only while the sessions still exist.

So for an AI-built project, the handover adds three things to the usual list:

• The spec as built, with every version and change — the record of intent that otherwise lives in chat transcripts nobody hands over.
• The agent’s working files: CLAUDE.md or AGENTS.md, the settings, hooks, custom commands and skills, and the list of connected tools (MCP servers), with what each needs to run.
• The tests, as the proof of what the code does, and the decisions behind what it does not.

Rules for a HANDOFF.md

1. Write it before the context runs out, not after: ask for it at a natural stopping point.
2. One file per piece of work, overwritten each time; commit it with the work.
3. Point to the spec, the plan and the commits; do not copy them.
4. Record what failed and why — the one thing nobody can reconstruct.
5. Write open questions as questions, with the person who decides.
6. Decisions go to the decision log and the spec, not only to the handoff.
7. No passwords, keys or customer data — the file is in the repository.
8. Have the next session say the plan back before it changes anything.
9. Delete it, or move it to the history, when the work is merged.

Where Specroot fits

This is the problem Specroot works on: the requirements and the decisions behind them — every version, every approved change, and who agreed it — kept as one record that outlives any session, so a handoff can point to it instead of carrying it. Specroot for agencies and consultancies.