# Session handoffs: keeping a coding agent on track for weeks > A coding agent starts from zero every session. How a handoff file, read first and rewritten last, keeps it on track on the same product for weeks. - Author: Simone Tolomelli - Published: 16 October 2026 (2026-10-16) - Category: Vibe coding - URL: https://sweetpal.ai/en/blog/coding-agent-handoff-sessions - Versione italiana: https://sweetpal.ai/blog/agente-coding-handoff-sessioni.md - Publisher: Sweet Pal (https://sweetpal.ai) — AI companion for type 1 diabetes --- A coding agent starts every session remembering nothing of the last one. To keep it working on the same product for weeks, we give it a single file to read first, `docs/HANDOFF.md`, which says where we are, what's in production, what's open and how to pick up. One rule keeps it alive: whoever does the work rewrites it at the end of every piece of work, in the same session. Project instructions aren't enough. Each repository's `CLAUDE.md` holds the rules (how migrations are done, where secrets go, how we use git), and they're stable, changing a few times a month. The state of the work changes every day, sometimes every hour: a function just deployed, a test still to run, a decision made in conversation. Put it in the instructions and they'd grow long and soon wrong. It needs a place of its own, and that place is the handoff file. In the iOS app's repository, which dates from late June, about 140 of 660 commits touch `docs/HANDOFF.md`; in the admin dashboard's it's 68 of 156. That isn't bureaucracy: it's the small price of not having to explain everything again every morning. The file opens with a block that says when to read it: first, at every new session and every time the conversation is reset. Then a few sections, always the same: **where we are**, with the date, meaning what's in production, on which branch, at which version; **the latest work**, meaning what was asked, found, done and tested, a section that is rewritten rather than appended to; **what's open**, and whose it is; and at the bottom a log, one line per job, for anyone who needs the history. It's short on purpose. Detail lives in the documents it links to. ## An old handoff is worse than none Our handoff contains one sentence worth more than the others: a handoff that isn't about the last thing done is worse than nothing. A file two days out of date doesn't say "I don't know"; it confidently says something false, and an agent that reads it starts from there and builds on top. That's why the update isn't postponed to the end of the day or left to a later session: whoever worked does it, before closing. And for the same reason every statement of state carries a date. "It's in production" without a date can't be weighed; "in production since 8 October" can. The most useful distinction we've learned to write down is between done and verified. In the dashboard's handoff, at the end of every job, there's a line saying exactly how far testing went: types and build passing, the new questions tried against the real model, the chain reread from the database, and then, in bold, **not tested in the browser**. To a person it seems too obvious to write. To an agent arriving the next day it changes everything, because it knows the next step isn't adding, it's testing. Traps are learned once, if they're written where people trip. During a stretch of intense work, the app's production was running commits newer than those on the remote repository, and the handoff said, with two exclamation marks, to deploy functions from the local `main` and never from the remote: doing it from the remote would have wiped out work already in production and reopened a bug that had just been closed. On the dashboard, the hosting platform doesn't report when a deploy has finished, and a screenshot taken two and a half minutes after a push still showed the old version. The handoff says it plainly: before hunting a bug, check that the page shows the new text. A handful of words that save an afternoon spent fixing code that wasn't online yet. And when a choice is made by a person rather than by the code, the handoff records it with the name, the date and sometimes the exact words: "no replies without the language model: even small talk is written by the model". A later session, which might find the opposite reasonable, knows the question is closed and by whom. ## A map: when to read what Next to the handoff sits `docs/README.md`, with a two-column table: the file, and when to read it. Not "what it's about", but **at which moment you need it**. A document on glucose forecasting says to read it before touching the forecasting engine; one on the model that classifies messages opens with the three things to know before touching anything at all. Every document starts with the same block, "when to read this file", and follows the same order: vision, real state checked against code and database, backlog, dated log. One workstream, one file: if a document starts covering two things, it gets split. The same mechanism works across repositories. When the website needed the dashboard to manage its App Store links, the session working on the site wrote a handoff document for the one that would work on the dashboard: the table to use, the columns, who reads and who writes, the things not to do. The dashboard session built on that, and nobody had to explain anything twice. Coding tools with persistent memory store small facts between sessions, and we use them. But they serve a different purpose: they remember **how to work with us**, not **where the work stands**. Don't start test servers on the port other processes already use; for scrolling bugs on iPhone, don't trust emulation, ask for a test on a real phone. Those are habits. The state of the work has to live in the repository, where every session and every person can see it, and where git history says who changed it and when. **In short:** - A coding agent remembers nothing: the state of the work goes in a file it reads first. - The "latest work" section is rewritten, not appended to; every statement of state has a date. - Saying what was tested and what wasn't tells the next session its next step. - Traps and human decisions are written where people trip over them, with names and dates. - The agent's memories are for habits; the state of the work lives in the repository.