The most expensive software problem we get called about is not a bug. It is a company that owns a product nobody on their side can change.
It happens gradually. The build goes fine. The launch goes fine. Then the agency's contract ends, and it turns out the deployment runs from one engineer's laptop, the environment variables live in a Slack message, and no document anywhere explains why the billing job runs at 3am.
That product is not finished. It is hostage.
What a real handover contains
The repository, in your organisation. Not a zip file, not a fork — the actual repository, in an account you own, with the full commit history. You should have had this since week one.
Every account in your name. Hosting, domain, error tracking, analytics, the app store listings, the payment provider. Where an agency needs access, it should be as an invited member of your account, removable by you.
A README that a stranger can follow. Clone, install, run, test, deploy. If a new developer cannot get the project running locally in under an hour using only that file, the handover is incomplete.
An architecture note. One page. What the pieces are, which one talks to which, and — most importantly — why the non-obvious decisions were made. Future maintainers do not need your reasoning to agree with it. They need it so they do not undo it by accident.
A deployment that runs from CI. If shipping requires a specific person's machine, you have a single point of failure with a pulse.
A recorded walkthrough. Thirty minutes, screen recorded, covering the admin areas, the scheduled jobs, and the three things most likely to go wrong. This costs us half a day and saves clients weeks.
How to check before you sign
Ask any prospective partner these three questions:
- Whose GitHub organisation will the code live in during the build? The answer should be yours, from the start.
- What exactly do we receive at handover? If the answer is vague, the handover will be too.
- Can we take this to another developer without you? Watch how comfortable they are with the question.
None of this is generous. It is the baseline. We put it in writing because a client who could leave and chooses to stay is a much better relationship than one who cannot.
The other reason it matters
Building for handover makes the software better while you build it. Code you know a stranger will read gets clearer names. Infrastructure you know someone else will run gets documented. Decisions you know you will have to justify get made more carefully.
Writing for an audience improves the writing. The same is true of code.