What a handoff file actually is
A handoff file is a plain-text document — usually named something like HANDOFF.md — that lives in your project folder and tells the next AI session everything the last one knew. What the project is. What's been built. What broke and how it got fixed. What's deliberately weird and shouldn't be "cleaned up." What's next on the list.
Think of it like a shift change at a hospital. The outgoing nurse doesn't just wave at the incoming one and hope for the best. There's a structured briefing: this patient, this medication, this thing to watch for. AI sessions need the exact same ritual, because each new conversation is, quite literally, a new shift worker who has never met your project before.
The format is simple on purpose. A good handoff file usually contains: a one-paragraph project summary, current versions and file locations, the deploy process, recent changes, known gotchas, standing rules ("never touch the footer text"), and the immediate next task. That's it. No prose poetry required.
Why .md and not .txt, .doc, or something fancier
Markdown won this job for three reasons. First, it's pure text. No hidden formatting codes, no binary blobs, no "this file was created in a newer version" warnings. Any AI, any editor, any operating system reads it identically. A Word document carries invisible baggage; a Markdown file carries only what you typed.
Second, it has just enough structure. Headers, bullet points, bold text, and code blocks — the four things a handoff actually needs. AI models are trained on billions of Markdown documents (most of GitHub, most technical documentation, most of the modern internet's writing layer), so they parse the structure natively. A ## Known Issues header isn't just visually distinct to you — the model recognizes it as a section boundary and treats the content accordingly.
Third, it plays perfectly with version control. Because Markdown is plain text, GitHub can show you exactly what changed between versions of your handoff file, line by line. Your project's memory gets its own history.
A brief, genuinely interesting history of the .md file
Markdown was created in 2004 by John Gruber, the writer behind the blog Daring Fireball, with significant input from Aaron Swartz — the programming prodigy who also helped shape RSS and later co-founded Reddit. Their goal was almost comically modest: let people write for the web in a format that looks readable as plain text, then convert it to HTML. The syntax was borrowed from how people already formatted plain-text emails in the 1990s — asterisks for emphasis, dashes for lists.
For years it was a niche blogger's tool. Then GitHub adopted it for README files around 2008, and that decision quietly made Markdown the default language of software documentation worldwide. Today it powers Reddit posts, Discord messages, Notion pages, and — fittingly — it's the format AI chatbots themselves use to structure their own responses. When ChatGPT or Claude gives you a bulleted list with bold headers, you're looking at rendered Markdown. The format your AI thinks in is the format you should brief it in. That's not a coincidence; it's an advantage.
Which AIs need a handoff file — and for what work
The honest answer: any AI, for any work that spans more than one session. But the need scales with the type of work:
- Coding and web projects — critical. Version numbers, file structures, deploy pipelines, and "we already tried that, it broke X" knowledge evaporate between sessions. This is where handoff files earn their keep daily.
- Long-form writing projects — high value. Tone rules, character notes, style decisions, and what's already been covered.
- Research and analysis — high value. Sources already checked, conclusions already reached, dead ends already explored.
- One-off questions — skip it. Asking what wattage your microwave should be does not require a briefing document.
This applies across ChatGPT, Claude, Gemini, Copilot, and everything else. Some of these tools now offer built-in memory features, which leads to a tempting question — and a trap.
Should you just depend on the AI's built-in memory?
No. Use it, enjoy it, but don't depend on it. Built-in AI memory has three structural problems. You can't fully see it — you don't know exactly what was stored, what was paraphrased, or what was silently dropped. You can't carry it — memories in ChatGPT don't follow you to Claude, and vice versa. The moment you switch tools, your project history stays behind like luggage on the wrong carousel. And you can't trust its priorities — memory systems decide what's "important" using their own logic, which may not match yours. The version number you desperately need might lose out to the fact that you once mentioned liking coffee.
A handoff file inverts all three problems. You wrote it, so you know exactly what's in it. It's a file, so it goes wherever you go. And you decided what mattered. AI memory is a convenience; the handoff file is the record.
The consequences of not using one
Skipping the handoff file doesn't fail loudly. It fails expensively, in slow motion. You spend the first twenty minutes of every session re-explaining the project — and you will forget details, because you're human. The AI then confidently fills the gaps with plausible guesses: it edits the wrong file, "fixes" something that was intentional, reintroduces a bug you killed two weeks ago, or rewrites copy on a live page that was never supposed to change.
The worst failures are the silent ones. An AI with no context doesn't know that your homepage header is hardcoded for a reason, or that two files must never have matching version numbers, or that a folder of old .kt files on your desktop is a decoy graveyard and not the real source code. Without a handoff file, every session is an opportunity to relearn those lessons the hard way — usually in production.
Switching between smart and cheap models — does the handoff survive the trip down?
Here's a question almost nobody asks: if a top-tier model writes a brilliant handoff file, can a smaller, cheaper model actually use it? Yes — and often better than it can do anything else.
The reason is that reading comprehension is the strongest skill smaller models have. What separates a frontier model from a budget one is mostly reasoning under ambiguity — figuring things out from incomplete information. A good handoff file removes the ambiguity. It converts "figure out my deploy process" (hard reasoning) into "follow this written deploy process" (easy instruction-following). You're essentially pre-paying the thinking with the expensive model so the cheap model can coast on the results.
There's one catch: the handoff must be written for the audience. A high-level model briefing another high-level model can be terse and assume context. A handoff destined for a smaller model should be more explicit — full file paths instead of "the usual file," exact commands instead of "deploy as normal," and zero reliance on the reader inferring anything. A useful trick: at the end of a session, ask your top-tier model to "write the handoff file so a less capable AI could follow it without guessing." The smart model knows exactly what the dumb model will trip over.
So — do you need one?
If you've ever started an AI session with "okay, so where we left off was..." — you already need one, and you've been writing it from memory, badly, every single time. The handoff file just moves that ritual into a document that doesn't forget, doesn't paraphrase, and doesn't get tired.
Start small. One file, named HANDOFF.md, in the root of your project. Five sections: what this is, current state, recent changes, known gotchas, next steps. Update it at the end of every working session — better yet, make the AI update it as its last task, then read what it wrote. Two minutes of maintenance buys you a project memory that outlives any chat window, any model upgrade, and any company's memory feature. The AI will forget you tomorrow. The file won't.