Your last week on a project is the week you have the least time. There are tickets to close, a laptop to return, and a calendar full of people asking whether you can "just explain the one thing" before Friday. So the handoff becomes a long Slack message, posted in a channel, and it disappears into scroll history by the next sprint.
A project handoff note is the fix, and it is smaller than you think. It is not documentation for the whole system. It is a short written file that lives in the repository, points into the context that already exists, and adds the handful of things that only ever lived in your head.
This article gives you the five things such a note must say, a way to reference existing memory and instructions instead of retyping them, a method for capturing the decisions nobody watched you make, and a checklist for your last day. All of it works with plain Markdown files, whatever assistant your team uses.
Why a goodbye message in Slack is not a handoff
Chat is the wrong container for a handoff, for three boring reasons.
It is not where anyone looks. Your successor will open the repository first. They will read the README, then CLAUDE.md or AGENTS.md, then the code. They will not scroll a channel from three months ago, and they will not know which channel it was.
It is not searchable in the way that matters. Even with good chat search, you need to guess the words. A file called HANDOFF.md needs no guessing.
It does not travel. When the project is cloned onto a new machine, or handed to a contractor, or picked up by a team in another timezone, the chat history stays behind. Only the repository moves.
There is a fourth reason that is specific to AI-assisted work. Your successor will not read the project alone — they will read it with an assistant. An assistant can read a file in the repository and use it. It cannot read your Slack message. So every piece of knowledge you leave in chat is knowledge that is invisible to the tool your replacement will spend most of their day with.
What your replacement cannot get from the code alone
Before writing anything, it helps to be precise about the gap. Code answers "what does this do?" quite well. A competent developer plus a competent assistant can read your repository and describe the system accurately.
Here is what they cannot recover:
- Why an option was rejected. The code shows the queue you built. It does not show the two designs you tried and abandoned, and it does not stop the assistant from proposing one of them again next week.
- What is deliberately ugly. The retry with the odd sleep, the duplicated validation, the hard-coded region string. Each of those looks like a bug. Some of them are load-bearing.
- What is half-finished. A branch you never merged. A migration written but not run. A feature flag that is off in production and on in staging, on purpose.
- Who to ask. The one person on the platform team who knows why the build agents need that cache directory.
- What is about to break. The certificate that expires in November. The vendor API version that gets retired next quarter.
None of that is in the code, and most of it is not in your issue tracker either. It is in your head, and your head is leaving.
The five things a project handoff note must say
Keep the note to one page. If it grows past two screens, the useful parts get skipped. Five sections is enough.
1. Where you actually are
One paragraph on the current state, in plain language. Not the roadmap — the truth.
## State as of 2026-09-26
The billing rewrite is about 70% done. New invoice generation is live
behind the `invoices_v2` flag (staging on, production off). The old
path still handles all production traffic. Refunds are untouched and
still use the v1 code.
2. What is in flight, and where it lives
Every unfinished thread, with its location. Branches, draft pull requests, uncommitted work on your machine (push it), scripts you keep in a scratch folder.
## In flight
- `feat/invoice-pdf` — renders fine, fails on multi-currency. Stuck on
rounding; see memory note 2026-09-18.
- Migration `0042_invoice_totals.sql` written, NOT run anywhere.
Needs a backfill first.
- No open work on refunds. Do not start it before the flag flips.
3. The traps
The list of things that look wrong and are not, plus things that look fine and are not. This is the highest-value section, and the one your successor will thank you for. Be blunt.
## Traps
- `syncOrders()` retries exactly 3 times then gives up silently.
Intentional: the upstream API double-charges on the 4th call.
- Tests pass locally with a seeded DB only. `pnpm db:seed` first.
- The staging webhook secret differs from production. Rotating one
does not rotate the other.
4. Deadlines that are not yours anymore
Anything time-bound that will fire after you leave. Certificates, contract renewals, deprecations, scheduled jobs that nobody monitors.
5. Where the rest of the context is
The shortest section, and the one that keeps the note from becoming a book. A list of pointers: instruction files, memory, decisions, saved sessions. More on that next.
Point to the context that already exists, do not retype it
If your project has been keeping context as you went, most of the handoff is already written. A good note is mostly an index.
A layout that works:
project/
CLAUDE.md # how we work here
AGENTS.md
HANDOFF.md # the note you are writing now
.prjcontext/
memory/
decisions.md
rejected.md
open-questions.md
sessions/
2026-08-14-sync-design.md
Then the last section of your note is four lines:
## Where the context lives
- Instructions: `CLAUDE.md` (Claude Code), `AGENTS.md` (Codex and others)
- Decisions and why: `.prjcontext/memory/decisions.md`
- Approaches we dropped: `.prjcontext/memory/rejected.md`
- The sync design conversation: `.prjcontext/sessions/2026-08-14-sync-design.md`
If those files do not exist yet, your last week is a bad time to start from zero — but it is a fine time to write the five or six entries that matter most. The guide on project memory for AI coding has templates you can fill in quickly, and which AI coding sessions are worth keeping helps you pick the two or three transcripts worth saving rather than trying to keep everything.
One thing to resist: do not copy the content of your memory files into the handoff note. Two copies drift, and within a month nobody knows which is current. The note points; the files hold.
Write down the decisions nobody else saw you make
Some decisions went through review. Those are safe — there is a pull request, a comment thread, maybe an architecture document. The dangerous ones are the decisions you made alone, in twenty minutes, in a session with an assistant, because they were small at the time.
Those are the ones that look arbitrary later. A colleague will find them, assume they were accidental, and "clean them up."
Spend an hour listing them. Go through your recent work and ask: did I choose something here, where a reasonable person would have chosen differently? Then write each one in three lines.
### 2026-09-09 — Totals stored, not computed
Decision: Store invoice totals as a column instead of summing lines.
Why: Historical invoices must not change when tax rules change.
Consequence: Totals and lines can diverge. `verifyTotals()` checks this nightly.
Status: Active
That format is deliberately small so you will actually use it under time pressure; the longer version is in lightweight decision records for AI-assisted projects. The reason it matters more at departure than at any other moment: while you are on the project, you are the fallback for missing reasons. After you leave, there is no fallback.
Also write down the decisions you regret. "We stored dates as strings in the events table. It was wrong. Changing it needs a migration and a backfill; here is roughly how." An honest regret saves your successor weeks of trying to understand why it was done that way on purpose.
A handoff checklist for your last day on the project
Work down this list. It takes an afternoon, not a week.
| Step | What you do | Why it matters |
|---|---|---|
| 1 | Push everything, including unfinished branches | Work on your laptop dies with your laptop access |
| 2 | Write HANDOFF.md — the five sections above | The one file your successor will open |
| 3 | Add the solo decisions to your decisions file | Reasons vanish first |
| 4 | Update CLAUDE.md / AGENTS.md if it is stale | The assistant follows it literally |
| 5 | Save the two or three sessions worth keeping | Raw reasoning, not summaries |
| 6 | Remove yourself from things only you can do | Scheduled jobs, alert routing, on-call |
| 7 | Check nothing secret is in the files you added | Handoff notes attract pasted credentials |
| 8 | Do a live walkthrough, then point at the note | Conversation for questions, file for facts |
Two notes on that list.
Step 7 deserves real attention. Handoff notes are written fast, and they are exactly where people paste a connection string "so it is not lost." Read what you wrote before you commit it. Keeping secrets out of your AI context covers the habits; the short version is that credentials belong in your secret manager, and the handoff note should say where they are, never what they are.
Step 8 is the pairing, not the replacement. A 45-minute call where your successor clones the project and you watch them get it running is worth more than another page of prose — and it tells you which parts of your note are unclear. The onboarding side of this is covered in onboarding a new contributor with project context; read it once from the other chair and you will write a better note.
If the person taking over works on a different machine, in a different city, they will also need everything to arrive intact in one step. That is the same problem as continuing an AI coding project on another machine — the handoff is just the version where the other machine belongs to someone else.
How PrjLab handles this
We built PrjLab so the things you hand over travel together instead of being split across a repository, a chat channel and one laptop's session history.
- A PrjLab repository holds your files plus three kinds of context:
.prjcontext/instructions/(andCLAUDE.md/AGENTS.mdat the project root),.prjcontext/memory/for decisions and notes, and.prjcontext/sessions/for the conversations you chose to keep. YourHANDOFF.mdsits with them. prj pushcreates an immutable version you can open in the browser, with the list of changes and a line diff against the previous version — so "what did they change in their last week?" has an answer.- Share the repository by handle with your successor as a reader (view and clone) or a writer (also push). When your access should end, removing you takes effect immediately.
- They run
prj cloneand get the code, the instructions, the memory and the saved sessions in one step, on their machine. - The CLI skips
.envfiles, key files and credential folders, plus anything in.gitignoreor.prjignore. It is a safety net, not a complete secret scanner, so runprj statusand read it before your final push. - Repositories are private by default. If you make one public, its memory and sessions become readable too — review them first.
The docs walk through prj init, prj status and prj push end to end.
Frequently asked questions
How long should a handoff note be? One page, two at most. If it is longer, the important lines get skipped. Length belongs in the memory and decision files the note points to.
Should I write the handoff note with an AI assistant? Yes, for the state and in-flight sections — an assistant can read your recent branches and diffs and draft a summary you correct. Do not let it write the traps and decisions sections; those are exactly the parts it cannot know.
What if the project has no memory files, no decision records, nothing? Then write the five-section note and add three decision entries. Three honest entries beat an empty folder, and they give your successor a file to keep adding to.
Who should I write it for — a person or an assistant? A person, in plain language. Files written clearly for a human turn out to work well as assistant context too; the reverse is rarely true.
If you are leaving a project this month, the fastest way to make the handoff survive you is to put it beside the code — start with the getting-started guide.
