I recently handed over several systems I had been the only person running. Web apps, a mobile app, databases with real user data, hosts I had configured by hand over a long time.
Writing the documents was the part I expected to be hard. It was not. The hard part was a question I could not answer by writing more: what does the person who inherits this do in their first session, before they know anything, while they are most likely to break something and least likely to realise it.
The failure mode of a handover is not an absence of documentation. It is a successor with a confident and slightly wrong mental model, making a reasonable change, on a system where the reasonable change is wrong.
So along with the documents I left a prompt. It is written to be pasted into an AI coding assistant at the very start of the first working session, and its entire job is to stop day one from being a day of changes.
The template
Everything in square brackets is yours to replace. Nothing else needs changing.
You are taking over [SYSTEM NAME], [ONE SENTENCE ON WHAT IT DOES AND WHO USES
IT], handed over in [MONTH YEAR]. It is [in production / an internal pilot /
pre-launch] and it holds [WHAT IT HOLDS: real customer data, employee PII,
payment records, nothing sensitive].
The previous maintainer has left. Assume no access to their accounts, their
machine, their domain or their hosting logins. Nothing personal of theirs should
be reused.
Read, in this order, and do not skip the risk register:
1. [ENTRY POINT DOC, e.g. CLAUDE.md or README in the repo root]
2. [THE HANDOVER DOC, and the section you most need read]
3. [THE SECRETS OR CREDENTIALS DOC]
4. [THE ACCESS CHECKLIST]
Then confirm the running system matches what those documents describe. They were
verified against the host on [DATE OF LAST VERIFICATION], so treat this as a
handover check and a chance to catch anything that has moved since:
- what is running, started from which file, on which host
- which data stores actually hold live data, and which are leftovers
- whether the database is reachable, and its size and table count
- whether a backup exists, how old it is, and whether anyone has ever
restored one
- what is publicly reachable, checked by probing from outside the machine
rather than by reading a firewall config
Report what you found, anything that no longer matches the documents, and the
three things you consider most urgent, with your reasoning.
Be aware of these known traps:
- [THE THING NOBODY WOULD GUESS, e.g. the live process is started from a file
whose name says it is not the live one]
- [THE DECOY, e.g. two data volumes exist and the obvious one is empty]
- [THE UNVERIFIED ASSUMPTION, e.g. these calculations were never checked by
anyone qualified]
Change nothing in this first session. If you believe something needs changing
immediately, say so and explain why, and wait.
Rules for every session after this one:
- Back up before touching data, and verify the restore by row count. A backup
nobody has restored is not a backup.
- Never print a secret into a terminal, a commit, a log or a chat.
- [THE RISK THAT IS NOT A CODE RISK, e.g. statutory or regulatory
correctness was never independently verified. Do not assume it is right
because the code looks confident.]
- Say plainly what you did not do, did not test, or skipped.
- When you change something these documents describe, change the sentence in
the same commit.
Filling in the brackets
Most of it is mechanical. Three of them are worth thinking about, because they are where the value is.
The traps. This is the part only you can write, and the part that saves the most time. A trap is not a bug and not a todo. It is anything where the obvious reading of the system is wrong. My own list included a live service started from a file named for a different environment, and two data volumes where the one with the obvious name was not the one in use. Neither is discoverable by reading the code. Both cost a day if you meet them alone at speed. If you cannot think of any, you probably have not run the system under pressure.
The date of last verification. Give the successor a date and they know exactly how much to trust the pack. Give them no date and every sentence is equally suspect, which means they will either re-derive everything or trust all of it, and both are bad. This line also quietly admits that documentation decays, which is more useful than pretending it does not.
The risk that is not a code risk. Every system I handed over had one thing where being wrong had consequences outside the codebase. Tax and statutory calculations, in my case, never independently checked. That belongs in the prompt itself rather than only in a document, because it is the single item where a confident assistant and a confident successor can compound into a real problem for someone who is not in the room.
Why it refuses to change anything
The instruction to change nothing on day one is the part people push back on, and it is the part I would keep if I could keep only one line.
A new maintainer's first instinct is to demonstrate value, and an assistant's default is to be helpful, which means acting. Put those together on an unfamiliar production system and the first session produces a change nobody can evaluate, including the person who made it. Reconnaissance has an output too. Three ranked urgent findings with reasoning is a better first day than a merged fix, because it can be checked.
The other half of that instruction matters as much: if something genuinely needs changing now, say so and wait. It is not a gag order. It is a requirement to surface the judgment instead of acting on it silently.
The part that outlives the prompt
A prompt has one weakness. Someone has to remember to paste it, and by the third week nobody does.
So do not let this be the only copy. Put the same traps, risks and standing
rules into the file your assistant loads by itself in that repository, which for
Claude Code means a CLAUDE.md in the root. Then the knowledge arrives in every
session, for every person, without anyone remembering anything.
And keep it true. When a sentence in it stops being accurate, fix it in the same change that made it inaccurate. A confidently wrong handover document is worse than no document, because it gets trusted by default and nobody goes looking for a second source.