Code Handover Done Right: Owning What You Paid For

You’ve spent six months and six figures building software. The agency says “it’s done.” You get a GitHub link and a wave goodbye. Three months later, you need a bug fix and can’t find anyone who understands the code. Welcome to the code handover problem.

This happens constantly. Not because agencies are malicious-usually because there’s no standard for what “done” actually means. You end up renting code instead of owning it.

The Real Cost of a Bad Handover

A poor handover creates a hidden tax on your business. You’ve paid for the build, but you’re not free. You’re locked in-either paying the original agency inflated rates to fix things, or hiring new developers to reverse-engineer someone else’s work.

A fintech we worked with inherited a codebase from another shop. The previous agency had:

• No documentation of database schema decisions
• Hard-coded API keys scattered across config files
• Tests that covered 12% of the code
• Deployment process that only one person understood (and they’d left)

Fixing this took two weeks and cost AUD 8,000 before they could ship a single feature. They’d already paid AUD 45,000 for the initial build.

The real kicker: this is preventable. A proper handover costs maybe 5-10% more upfront and saves multiples of that downstream.

What a Proper Code Handover Includes

Here’s the non-negotiable list. If an agency can’t or won’t do this, that’s a red flag:

1. Complete architecture documentation – Not essays. A one-page diagram showing services, databases, APIs, external integrations, and data flow. Written for a smart developer who’s never seen the code before.
2. Setup instructions – A developer should go from zero to “local environment running” in under 30 minutes, following a README. If it takes two hours of debugging, the documentation is bad.
3. Database schema and migrations – Every table explained: why it exists, what each field means, constraints, and indexes. Plus: a dump of anonymised production data for testing (if applicable).
4. Deployment process – Exact steps to push code to staging and production. CI/CD pipelines documented. Rollback procedure included. No “ask Dave, he knows how to deploy.”
5. API and environment documentation – Every environment variable explained. Every API endpoint documented (request/response format). Third-party service keys and credentials stored in a password manager you own, not scattered in code.
6. Test suite with meaningful coverage – Aim for 60-80% coverage of critical paths. Not perfect, but good enough that a new developer can refactor without breaking the app. Tests should run locally and in CI.
7. Known issues and technical debt log – Every hack, every “we’ll fix this later,” every performance issue. Prioritised. So your next developer doesn’t spend a week finding out that the payment webhook sometimes times out.

All of this should fit in a GitHub repo (documentation in the README and a `/docs` folder) plus a password manager you control. Not in Slack messages. Not in the agency’s Confluence. Yours.

The Architecture Question: Should You Care?

You should care enough to ask questions. You don’t need to be a developer, but you need to understand the shape of things.

Ask:

• Where does the data live? (AWS? Managed database? Which region?)
• What happens if the main database goes down? (Is there a backup? How long to restore?)
• How do you add a new feature? (Is it easy, or will it take two weeks of refactoring?)
• Can anyone deploy, or just one person?
• What’s the hosting cost per month?

A competent agency can answer all of these in plain English. If they’re vague, they don’t know-which means your developers won’t either.

Who Should Do the Handover?

Not the project manager. The lead developer who built it.

The handover should be a working session, not a presentation. Your developer (or someone you’re hiring) sits with the agency’s developer. They walk through the code together. They deploy something. They fix a small bug. Your developer asks dumb questions. The agency developer answers them.

This takes 2-3 days. It’s worth it. Your developer leaves knowing where the pitfalls are and who to call if something explodes at midnight.

Money Talk: What This Costs and Saves

A proper handover on a AUD 50,000 project might add AUD 3,000-5,000. That’s 6-10% more.

Without it, you’ll spend that many times over in the first year:

• Finding and hiring developers who can work with the code (extra vetting time)
• Paying those developers premium rates because they’re learning your system
• Emergency fixes when deployment breaks things
• Refactoring badly-architected features before you can build new ones

A startup we know built an MVP without proper handover docs. Six months later, they hired a developer. That developer spent two weeks just understanding the code. If they’d paid AUD 4,000 for proper documentation upfront, they’d have saved AUD 8,000 in developer ramp-up time alone.

How to Enforce This in Your Contract

Don’t assume it’ll happen. Put it in writing:

• “Final payment held until: (a) documentation is complete, (b) local setup works per README, (c) 60%+ test coverage on core features, (d) deployment is reproducible without agency help.”
• Include a definition of “complete documentation” in the Statement of Work.
• Budget 5-10% of the total project cost for handover work (including developer time for you or your hire).
• Get a 30-day post-launch support window included. Issues found in the first month are the agency’s problem to fix.

These aren’t unreasonable asks. Any agency worth hiring will agree to them. If they push back, they’re not confident in what they’ve built.

Closing: Ownership Starts Day One

Code is a living thing. It will break. It will need changes. You’ll hire new developers. In five years, you might not work with the original agency at all. The code needs to survive that transition.

A proper handover is the difference between owning your software and renting it. The extra cost is insurance. And it’s cheap insurance.

If you’re building something new and want to talk through how to structure the build, delivery, and handover from the start, talk to Amora about your build. We ship MVPs in 28 days, and handover is baked into how we work.