Handoff — continue in a fresh session
Sessions get dumber as they fill up, and a fresh session forgets everything. The fix is a handoff — a short note that lets a brand-new session pick up exactly where you left off, but in the smart zone. It's the most useful pro habit in this whole workflow.
The three steps
Before you stop
Ask the session to write a handoff note into your repo (the first prompt below does it). Once the note is saved, you can close the session safely.
Clear, don't compact
Start a new session — don't "compact" the old one. Fresh context = smarter Claude: you keep the note's knowledge without the old chat's noise.
Resume
In the new session, point Claude at the handoff note (the second prompt below). It's back up to speed in seconds.
The two handoff prompts
Copy 1 — end the session (write the handoff)
Write a handoff note to docs/HANDOFF.md so a fresh session can continue this work. Include: (1) the goal, (2) what is DONE, (3) what is IN PROGRESS and the exact next step, (4) key decisions and things we ruled out, (5) files that matter and how to run the tests. Keep it short and factual.
Copy 2 — start the new session (resume)
Read docs/HANDOFF.md and the plan in docs/specs/[slug]/. Summarize back to me in 5 lines what we're doing and the next step, so I can confirm you're aligned. Then wait for my go-ahead before changing any code.
Notice the summarize-back step: it's your checkpoint that the new session actually understood where you are — Claude waits for your go-ahead before touching any code.
Two ways to carry context
There are two complementary ways to make context survive between sessions:
| Mode | How it works | Use it for |
|---|---|---|
| Pull | Keep plans, issues, and the handoff as files in the repo; any fresh session can read them | Where you are right now — docs/HANDOFF.md, the plan in docs/specs/ |
| Push | Put standing rules in a CLAUDE.md file at the top of your project; Claude reads it automatically every session | What's always true about the project |
Use CLAUDE.md for what's always true; HANDOFF.md for where you are right now.
Beware "doc rot"
Old plans can mislead a future session once the code has moved on. When a feature is finished, archive or delete its PRD and issues — a stale plan sitting in the repo is worse than no plan at all.
Adapted, with credit, from Matt Pocock's engineering workshop.