We Keep a Handoff Doc in Every Repo So AI Sessions Don't Start From Zero
AI sessions don't remember the last one. You come back to a repo after two days, open a new Claude Code session, and the model has no idea what was half-finished, what was deferred, or what's still broken. If you don't document the state, you re-derive it from scratch every time. That burns real time across a project.
We started keeping a HANDOFF.md at the root of every repo we work in, including our own site. It's the first thing updated at the end of a session and the first thing loaded at the start of the next one.
What Goes in It
Three sections: what was done, what's next, and any cautions.
What was done is a precise account of what shipped, what changed, and what state it's in. Not a summary. A log. Specific file names, commit hashes, what was tested, what a git status would show. "We added a caching layer" is useless. "Added cache in src/lib/airtable-cache.ts, invalidated on write via clearCacheForRecord(), confirmed cache hits in dev. Not yet tested under rate limits" is workable.
What's next is the actual remaining work, not the original project plan. It updates every session. Things that are blocked get annotated. Things that were deprioritized get moved down or removed.
Cautions are the things that will eat you if ignored. We've learned to make these explicit. One session we had a divergent local main that was ahead of origin. Every HANDOFF.md since has a state note with the exact branch, the ahead/behind count, and a warning if any destructive git operation would discard in-progress work.
A Real Example
The most recent entry in our own site's HANDOFF.md covers the full site redesign: a visual reskin from dark/3D/glow to a light-mode enterprise layout. The entry covers which branch carried the work before merge, which CSS tokens changed, which 22 components were deleted, which pages were touched, and three follow-up items that still need doing. It also has a caution: copy was kept verbatim from the old site and some marketing claims need verification before relying on them in front of prospects.
That entry is 25 lines. Reading it takes 90 seconds. A new session picking it up knows immediately what the site's current state is, what's live, and what to check before touching anything.
We have entries going back to a March session where we were debugging n8n workflows across multiple rounds. One entry documents exactly which node name in the automation pipeline cannot be changed without breaking a downstream $('NodeName').all() reference. That decision is still there. A future session touching that workflow won't rediscover it the hard way.
Why It Works
The handoff doc works because it's written for the person who comes next, not for yourself. When you've just spent three hours on something, the context feels obvious. Write it down as if you're briefing someone who wasn't there. That forces the right level of detail.
It also accumulates. Over time the doc becomes a log of every non-obvious decision made in the repo: why a particular approach was chosen, what was tried and ruled out, what's a known limitation versus a bug. That's institutional memory for a codebase that would otherwise live only in session transcripts nobody reads.
The alternative is what most teams do: open a session, describe the project from scratch, hope the model infers the right context, notice it's missing something, correct it, lose ten minutes re-establishing state. Multiply by every session across a months-long project.
The handoff doc is not a sophisticated technique. It's just the obvious response to working with tools that don't remember. The file costs nothing to maintain and pays back every time you open a new session.