What does a HANDOFF.md file do well?
A HANDOFF.md file is portable, readable, inexpensive, and easy to keep beside the code it describes. It can summarize the objective, current state, decisions, validation results, unresolved risks, and next action without requiring another service. Git can preserve changes to the file alongside the repository.
- One developer or agent controls the repository.
- The next actor already has access to the same checkout.
- The handoff can inherit the repository's visibility and retention rules.
- Sequential updates and Git history provide enough coordination.
What is the File Sufficiency Test?
The File Sufficiency Test asks whether one repository can provide the full continuity boundary. A file is enough when the evidence belongs in one repository, all receivers share the same access boundary, one current writer is sufficient, and Git attribution is adequate. If any answer is no, publish a durable handover that keeps the file but adds identity, access, revisions, review, and retrieval.
Question If yes If no
One repository owns all evidence? Keep the file with the code Attach cross-tool artifacts
One visibility boundary? Inherit repository access Apply handover-level access
One current writer at a time? Update HANDOFF.md Preserve parallel review threads
Git attribution is sufficient? Use commit history Record human and agent identity
Filename search is sufficient? Find it in the repository Index context across workspaces
No external continuation needed? Point the next agent to it Publish an MCP-readable handoverWhat does research say about structured agent handoffs?
A 2026 takeover study evaluated 724 runs per successor model across repository-only, raw-trace, summary-note, and structured-note handoff views. Context-bearing handoffs reduced median agent events by 20–59% and cumulative prompt tokens by 42–63% relative to repository-only takeover. The efficiency gains were consistent, while solved-rate effects were smaller and model-dependent.
- Repository state alone does not preserve predecessor intent, attempted work, or failure evidence.
- Raw traces reduced rediscovery but carried much larger initial prompts.
- Summary and structured notes provided bounded alternatives to an unfiltered trace.
- The study measures takeover efficiency; it does not prove that any specific product improves correctness.
Is a repository instruction file the same as a handoff?
No. Files such as AGENTS.md and CLAUDE.md primarily describe stable repository rules, while a handoff describes the changing state of interrupted work. A separate 2026 controlled study of 288 runs found no measurable correctness improvement from repository context-file strategy across the tested Claude Code and Codex tasks. Instructions can reduce rediscovery or improve compliance without supplying the implementation skill needed to solve a task.
Repository instructions Work handoff
Stable conventions and commands Current objective and progress
Architecture and coding rules Decisions and attempted approaches
Loaded across many tasks Created at a continuation boundary
Changes relatively slowly Changes with each revision
Answers "how do we work here?" Answers "what must happen next?"When should a team move beyond HANDOFF.md?
Move beyond a standalone file when work leaves the repository or becomes a shared operational record. The trigger is not file size; it is the need for an accountable continuation boundary that the repository alone cannot enforce.
- A person must review a specific HTML report, image, SQL file, or slide deck.
- Multiple agents need separate credentials and attributable actions.
- A company must isolate workspaces or grant access to selected users.
- Comments must remain anchored to exact artifact ranges across revisions.
- Another model or host must find and retrieve the current record through MCP.
- Retention, archival, export, or audit requirements extend beyond one repository.
What is the practical hybrid workflow?
Keep the low-friction file and add the platform only at a meaningful boundary. Generate or update HANDOFF.md during local work, commit it when repository history matters, then publish that file with the exact supporting artifacts before another person, model, tool, or team takes responsibility.
1. Maintain HANDOFF.md beside active code
2. Include objective, state, decisions, evidence, risks, and next action
3. Commit it when the repository is the source of truth
4. Publish it with logs, reports, images, or SQL when responsibility crosses systems
5. Let the receiver verify identity with handover.whoami
6. Retrieve the current revision and open annotations
7. Continue work and publish the next immutable revisionPrimary references