Learn

How to hand off work between AI agents



To hand off work between AI agents, have the agent that's finishing write a short note called NEXT.md saying what it did, what's half done and what it was unsure about, and keep a separate decisions.md file that records each decision and the reason for it. Put a line in your instruction file telling every agent to read both files before it starts. Keep all of it in a folder that every agent and every person on the project can reach.

That's the whole pattern. The rest of this page explains why it works, what good versions of the two files look like, and how to make handoffs work when the next agent belongs to someone else or runs on another device.


Why agents need a handoff note

A coding agent such as Claude Code or Codex starts a new session without the previous conversation. Whatever it worked out yesterday, the dead end it hit, the reason it chose one library over another, is gone unless it was written down. Some assistants keep a memory of facts about you, which helps with preferences, but a memory is a summary. It won't tell the next agent that the migration script is half written and fails on the third table.

What agents do reliably is read files. Claude Code reads CLAUDE.md when a session starts, Codex reads AGENTS.md, and either will open any other file those instructions point to. That makes a file the most dependable place to leave context for whoever comes next, whether that's the same agent tomorrow, a different agent this afternoon, or a colleague's agent in another time zone.

People do the same thing at shift changes. A nurse finishing a shift doesn't rely on the next nurse remembering the morning. They write it down, in a known place, in a known format. Agents need the same thing for the same reason.


The NEXT.md handoff note

NEXT.md describes the current state of the work. It's short, it's rewritten at the end of every session, and it answers four questions: what was done, what's half done, what to do next, and what the agent wasn't sure about.

Here's an example from a project to move a small company's invoices into a new accounting system:


markdown

# NEXT

Updated: 12 Nov, end of session (Claude Code)

## Done
Exported all 2025 invoices to `exports/invoices-2025.csv` (1,204 rows).
Mapped customer IDs to the new system's format: `mapping/customers.csv`.

## Half done
`scripts/import.py` imports invoices but skips any with a credit note
attached. About 40 rows. Not yet handled.

## Next
Handle credit notes (see the 11 Nov entry in decisions.md).
Then run the import against the test account, not production.

## Unsure
Three customers have two IDs in the old system. Listed at the bottom of
`mapping/customers.csv`. Ask Priya before merging them.
# NEXT

Updated: 12 Nov, end of session (Claude Code)

## Done
Exported all 2025 invoices to `exports/invoices-2025.csv` (1,204 rows).
Mapped customer IDs to the new system's format: `mapping/customers.csv`.

## Half done
`scripts/import.py` imports invoices but skips any with a credit note
attached. About 40 rows. Not yet handled.

## Next
Handle credit notes (see the 11 Nov entry in decisions.md).
Then run the import against the test account, not production.

## Unsure
Three customers have two IDs in the old system. Listed at the bottom of
`mapping/customers.csv`. Ask Priya before merging them.
# NEXT

Updated: 12 Nov, end of session (Claude Code)

## Done
Exported all 2025 invoices to `exports/invoices-2025.csv` (1,204 rows).
Mapped customer IDs to the new system's format: `mapping/customers.csv`.

## Half done
`scripts/import.py` imports invoices but skips any with a credit note
attached. About 40 rows. Not yet handled.

## Next
Handle credit notes (see the 11 Nov entry in decisions.md).
Then run the import against the test account, not production.

## Unsure
Three customers have two IDs in the old system. Listed at the bottom of
`mapping/customers.csv`. Ask Priya before merging them.

A few habits make the note useful. Name files by path so the next agent can open them without searching. Say plainly what's broken. Put questions for a person in the note rather than guessing at the answer. And keep it to a screen or so: a handoff note that runs to five pages gets skimmed, by people and agents alike.

Because NEXT.md is rewritten each time, it only ever shows the latest state. That's deliberate. The history lives elsewhere.


The decisions.md log

decisions.md is the history, or at least the part of it that matters. Each entry records one decision: the date, what was decided, why, and what was considered and rejected. Entries are added, never rewritten, so the file grows slowly over the life of a project.


markdown

# Decisions

## 11 Nov: Import credit notes as negative invoices
The new system has no separate credit note type. Importing them as
negative invoices keeps the customer balance correct.
Rejected: skipping them and adding by hand (too many, easy to miss).
Decided by: Sam, with Claude Code.

## 8 Nov: Keep old invoice numbers
Customers quote them on the phone. New numbers would confuse support.
Rejected: renumbering from 1.
Decided by: Priya.
# Decisions

## 11 Nov: Import credit notes as negative invoices
The new system has no separate credit note type. Importing them as
negative invoices keeps the customer balance correct.
Rejected: skipping them and adding by hand (too many, easy to miss).
Decided by: Sam, with Claude Code.

## 8 Nov: Keep old invoice numbers
Customers quote them on the phone. New numbers would confuse support.
Rejected: renumbering from 1.
Decided by: Priya.
# Decisions

## 11 Nov: Import credit notes as negative invoices
The new system has no separate credit note type. Importing them as
negative invoices keeps the customer balance correct.
Rejected: skipping them and adding by hand (too many, easy to miss).
Decided by: Sam, with Claude Code.

## 8 Nov: Keep old invoice numbers
Customers quote them on the phone. New numbers would confuse support.
Rejected: renumbering from 1.
Decided by: Priya.

The "rejected" line does more work than it seems. Without it, a fresh agent looking at the problem will often propose the option you already ruled out, and someone has to explain again why it won't work. With it, the agent can see the question was settled and move on. Teams without agents have the same problem, as why product decisions get relitigated describes, and how to keep a record of decisions so they don't get lost covers the habit more broadly.


Telling agents to use the files

Agents read the files they're told to read, so tell them. Add two or three lines to the project's CLAUDE.md or AGENTS.md:


markdown

## Handoffs
At the start of a session, read NEXT.md and decisions.md before doing anything else.
At the end of a session, rewrite NEXT.md. Add an entry to decisions.md for any
decision you made, including what you rejected and why.
## Handoffs
At the start of a session, read NEXT.md and decisions.md before doing anything else.
At the end of a session, rewrite NEXT.md. Add an entry to decisions.md for any
decision you made, including what you rejected and why.
## Handoffs
At the start of a session, read NEXT.md and decisions.md before doing anything else.
At the end of a session, rewrite NEXT.md. Add an entry to decisions.md for any
decision you made, including what you rejected and why.

Now every session starts with the current state and the reasoning behind it, and ends with both brought up to date. You can also say it in the first message ("read NEXT.md and continue"), which helps with assistants that don't read an instruction file automatically.

Keep these instructions in a file a person controls. If an agent could rewrite CLAUDE.md, it could quietly drop the handoff rule, or rewrite the instructions every later agent follows. In Fabric, instruction files such as CLAUDE.md, AGENTS.md and SKILL.md can't be changed by agents, even ones with write access, so the rule stays where you put it. Your agent instruction files are a security risk explains why that matters.


Handing off across people, agents and devices

On one laptop, this pattern works with a local folder. The trouble starts when the next agent isn't on that laptop. A co-founder's ChatGPT can't open a file on your disk. Claude on your phone can't see the project folder on your desktop. So someone copies the note into a message, and the handoff depends on a person remembering to do it.

A shared folder fixes that by putting the files where every agent can reach them. In Fabric, the desktop app mounts the drive on Mac, Windows and Linux, so Claude Code or Codex on your computer reads and writes NEXT.md like any local file. Claude and ChatGPT reach the same folder through Fabric's MCP server, and scripts can use the CLI or the API. How AI agents connect to a shared drive has the setup for each.

Picture the invoice project above with two people. Sam works in the evening with Claude Code on a laptop. Priya works mornings with ChatGPT, mostly from her phone. Sam's agent finishes at 11pm and rewrites NEXT.md. At 8am Priya asks ChatGPT what's waiting for her. It reads the note, sees the question about duplicate customer IDs, and she answers it. ChatGPT saves her answer as a note in the project folder. That evening Sam's agent reads it and merges the records. Nobody forwarded anything. Two founders, two agents, one plan follows a longer version of this story, and your agents, across all your devices covers the single-person version.

A few things about the drive help here. If two agents add to decisions.md at the same time, Fabric refuses whichever write was based on the older version, and that agent re-reads the file and adds its entry again, so neither entry is lost and no duplicate copy appears. When two AI agents edit the same file goes into the details. Earlier versions of NEXT.md are kept in version history, so you can look back at what the note said last Tuesday even though it's rewritten every day. And agents can run grep or full-text search across the whole drive on the server, which is useful when someone asks which project decided to keep old invoice numbers.

Access can be as narrow as the job. With Agent Vault, you can give an agent one project folder, choose whether it can only read or also write, and set the access to last for a single task, a day, a week or indefinitely. Every action it takes is logged, so you can see who updated the handoff note and when.


Where memory fits

Handoff files and agent memory do different jobs. Memory is good at standing facts, such as which tone a client prefers or that Priya approves anything over a certain amount. Handoff files hold the state of one piece of work. Fabric has both: its memory engine is described in state-of-the-art memory powering Fabric, and agent memory vs a shared drive compares the two. For the wider case for keeping agent work in shared files, read your AI agents need a shared drive, not a group chat.


Frequently asked questions

What is a NEXT.md file?

It's a short handoff note an agent writes at the end of a session, saying what it did, what's half done, what to do next and what it was unsure about. The next agent reads it before starting.

What should go in a decisions.md file?

One entry per decision, with the date, what was decided, why, what was rejected and who decided. Entries are added over time rather than rewritten.

Do AI agents remember previous sessions?

Coding agents such as Claude Code and Codex start each session without the previous conversation. Some assistants keep a memory of facts, but the state of a task is best kept in files the agent reads at the start.

How do I make an agent read my handoff note?

Add a line to CLAUDE.md or AGENTS.md telling it to read NEXT.md and decisions.md before starting, or say so in your first message.

Can Claude Code and ChatGPT share the same handoff file?

Yes, if the file is in a folder both can reach. In Fabric, Claude Code can use the mounted drive and ChatGPT connects through the MCP server, so both read the same NEXT.md.

What happens if two agents update decisions.md at the same time?

In Fabric, a write based on an older version of the file is refused. The agent re-reads the file and adds its entry again, so both entries are kept.

Should NEXT.md be overwritten or appended to?

Overwrite it each session so it always shows the current state. Keep the history in decisions.md, and in Fabric earlier versions of NEXT.md stay in version history.

Can an agent change the instructions that tell it to read NEXT.md?

Not in Fabric. Agents can't change instruction files such as CLAUDE.md, AGENTS.md and SKILL.md, even when they have write access.


Related pages


The workspace that thinks with you.

Ready when you are.

The workspace that thinks with you.

Ready when you are.

The workspace that thinks with you.

Ready when you are.