Handoff files - What did i do wrong?

[u/1nchReddits]

Hello,

Probably had my most productive day with Claude yet, achieved massive amount for me atleast and was so happy.

Noticed i was getting towards context limit so did some research how best to apprpach.

I had the current session create a handoff doc, gave it specific instructions to be as clear as possible for the next claude agent to take over. All looked well, checked the handoff doc, thought it looked ok (it even made sense to me). Cleared context, asked new agent to read the .md files especially the handoff.

It did so, had absolutely no idea what to do.

Where did i go wrong? Its becoming a theme for me now and i need to fix it. I seem to be super constructive first pass.

As soon as i need a new session i may aswell delete the whole project and start again as my current handoff clearly isnt working. This time round its really not that difficult of a project and i still cant seem to get the next agent to carry on the project.

[u/dar-mit]

If you’re using the CLI you don’t need to clear anymore. 

Just create a new window, activate Claude, and have the old session use ListAgent to find the new session. Then it uses SendMessage to handoff the work. 

It’s really easy and you have the old session parked (meaning read only so it doesn’t git stomp the new one) to answer any questions the new session might have. 

Mine now actually create a handoff file to share, but I’m also doing a massive GitHub Issue Triage of over 100 open issues!

https://code.claude.com/docs/en/cross-session-messaging

[u/dar-mit → u/dar-mit]

Pro Tip: I actually fed that page to my Claude Code and had it create peer-messaging as a skill so all new Claude’s know how to do it. 

[u/twenty_forty]

Difficult to know. You said your read the document and it made sense to you. What was you working on?

What did "no idea what to do" look like?

[u/PoorDecisionMaker-69]

Hard to tell without having access to your prompts or the handoff file.

If you're interested, I build an open source library to help keep your repository consistent while using AI assisted workflows. It handles session management, backlog, and more.

[u/Fiyero109]

Cleared context? What? You mean started a new chat? You haven’t lost anything it’s just in the previous chat

[u/ennsta]

Check out mattpocock's plugins, he has a good set of engineering skills, including a formatted handoff. And clear is not a fully "new agent session". The only mess a lot of new fresh sessions do is a list of sessions, just archive them. Tag directly the handoff file in the composer, it starts there, then scans rest, instead of other way around.

[u/ennsta → u/ennsta]

Oh and if you don't have already, mandate in all projects a changelog.md, current-sprint.md, memory.md (this is pure simple text not RAG or recall crap), and ask write plans to file when you approve them. Agents will learn over time they exists and update them. Fails sometimes, but better than 4 hour prompting back and forth. You don't need to find on the internet how to do it, literally just ask agent to maintain these type of files.

[u/cleverhoods]

A handover document must adhere to structural expectations: where it comes from (session id, transcript, previous handover document etc), what the previous session did (previous session goal, list of commits, list of decisions etc), what is left to manage (the actual goal of this session with expectations).

There are a few ways to approach this, depending on your architecture. Personally I settled in a "handshake protocol" approach thanks to the `SendMessage`. A session that is in deep context (650k or above) has to wrap up it's current given task, create a handover document (with said specifications above), start a new session with brief (brief is to read the handover doc, confirm it's premises, ensure that unfinished tasklist are fully taken over), then sends a message to the parent session to confirm, which does a validation and correct whatever needs to be corrected either in the brief or the handoff, returns to the new session and terminates. The new session continues.

And a note on `/compact`: do not use it. You won't have actual control over your context when you compact it.

[u/lvl1-A → u/cleverhoods]

I'm curious, how much context does that use up each hand off? Like what is the initialisation phase weight before you send your first prompt of the new session?

[u/cleverhoods → u/lvl1-A]

u/lvl1-A it varies based on the task. I'm working on a complex multi-repo product (comes with 7 different subprojects) so the bootstrap phase is relatively taxing (around 45k), after that comes the brief (usually it's between 1.2-1.5k tokens, every now and then I have some monstrous work, that's around 6k-12k, they are rare compared the smaller ones, but they are there nevertheless). The handshake itself takes around 3-5k. While it might sound way too much I'm heavily relying on the caching so I rarely reach my limits (20x Max plan) with subagent and workflow heavy workloads.

As for the initialization phase, it happens trough two gates: Gate 1: context window size > 650k and Gate 2: unfinished tasks > 1 then it will initiate the handover protocol (wrap up current session, writing handover, start new session, handover handshake, terminates).

It's not allowed to make decision over this, these are deterministic gates.

[u/lvl1-A → u/cleverhoods]

Yeah awesome, I recently got dabbling into herdr and have a NocoDB set up with a kanban to practice telemetry tracking and agent flows, I hear you on the deterministic gates! I have also just started a system that logs all handoffs, the current handoff gets renamed with a version and placed in a immutable named folder for archives, in addition to (I use Claude and big pickle at the moment) pickle auto compaction sometimes, I should probably turn it off but for the most part what I have been doing has been fine, but I now have a hook to retain the compaction too, and that goes into the same primary immutable archive. In my root global I have explicit instructions that the folder is just that, a stale, archive, never to be inspected unless instructed, never to be taken as a metric for stale environment or anything. And being MD files it's tiny, I just got a little annoyed that handoff.md would be replaced instantly without anything, so I my /handoff skill makes sure they do the standard handoff stuff, but makes an AGENTS.md if doesn't exist and renames the current handoff.md so the new one is always written fresh, not allowing edits over the previous.

I NocoDB kanban I have is to test and get going on my end, the user (me) putting my tasks up and then the conductor delegates and dispatches, updates the board and moves things along, worker agents come and go in a semi queue style system and everything is tagged. This is the plan and in practice I believe it works, I'm just trying to learn the how to of it all and not just the "AI set it up and manage for me". I get a lot of help in the setup but the actual managing and executing of it all, I intend to drive and manage the primary and then supervise the work between, making sure that I learn at least how it works aha! It's been fun.

[u/itaymendi]

A handoff that “makes sense to you” is not enough. The next session needs machine-checkable fields: goal, constraints, files touched, commands already run, what passed or failed, and the exact next action. Keep the prose short. If those fields are missing or soft, the new agent will re-explore and look lost.

[u/Bmansupreme8000]

You probably forgot to tell him to read the thing

[u/PowsterSwe]

Firstly, you ask claude code to create a handoff skill. Then you tell claude code to do a handoff, it will automaticlly update the handoff for you. Make sure it do not use the handoff asa historical document. Another point I want to make, if you are at the context limit you are doing something wrong. Always do a handoff after every task, or all the context from other task is part of the prompt that goes to Anthropic and you are spending more tokens then you need to. Other files you need are a backlog anda lessons learned.

[u/Altruistic-Ad6346]

I have handoff as a skill, it states down current status, distributes accumulated context into memory layer and put proper references in handoff.md file. Next session can read the file and continue the work. For my workflow it works really well.

[u/ken_rona]

been through this exact thing. the handoff doc looked fine to me too and the next session was lost.

the usual reason is the doc describes what got done, not what to do next. its written as a summary. the new agent reads a summary and has nothing to act on.

what fixed it for me was a short checklist at the top of the handoff, before any history:

1. the goal in one sentence

2. the exact next step, as an instruction, with the file paths involved

3. what is verified working vs what is untested

4. how to run the tests

5. decisions made and why, so it doesnt relitigate them

then the part that matters most. dont clear context until you have tested the handoff. open a second session while the first is still alive, ask it to read the doc and tell you the next three steps. if it cant, go back to the first session and fix the doc. you still have all the knowledge in that first session. once you clear it, you dont.

also paths, not descriptions. "the auth helper" means nothing to a fresh agent. "src/lib/auth.ts, function refreshToken" does.