Taking over a codebase from a previous agency: what to expect, and what it costs

You have decided to move your codebase to a new team. You expected the conversation to be about the work you want done next. Instead the new team wants to spend two weeks and a chunk of budget looking at what you already have, before committing to anything, and it is hard not to read that as either a stalling tactic or the first upsell.

It is neither, and the reason is worth understanding before you agree to it or refuse it. A takeover has three phases, and skipping the first one is what makes the other two expensive: assess what is actually there, stabilise whatever is dangerous, then start improving. The assessment is short and priceable. The stabilise phase is the one that surprises people. The improvements you actually wanted are third in the queue, and a team that puts them first is building on ground nobody has tested.

Why any serious team insists on a health check

There are two reasons, and only one of them is about them. The first: nobody can quote your work honestly without knowing what is underneath it. Adding a booking form to a well-structured system is a week. Adding the same form where the database has no concept of a customer, no tests exist to tell you what you broke, and the person who understood the payment code left in 2023, is not a week. You pay the difference between the guess and the truth either way. The only question is whether you find out during a two-week assessment or a six-month project.

The second protects you. The first thing a new team changes can break something nobody knew depended on it, and on an inherited system that risk is real rather than theoretical. Looking first is how they avoid taking production down in week one while learning the shape of the thing.

There is a third benefit suppliers rarely mention, because it works against them. A health check is the cheapest possible test of whether this new team is any good. You spend a small fixed amount and get back a document. If it is specific, prioritised and honest about what is fine as well as what is not, you have learned how they work. If it is vague, alarmist, or concludes that everything must be rebuilt in their favourite framework, you have learned more still, for the price of two weeks instead of a year.

What a health check actually looks at

A real assessment is not a developer glancing at the code and pulling a face. It should cover all of the following, and you should get the findings in writing.

• The code itself. Structure, how much of it is duplicated, how tangled the important parts are, and how much of it is actually reachable. Old code that nothing calls is a housekeeping problem, not a risk.
• Dependencies and versions. Which libraries and language versions are in use, which are out of support, and which have known published vulnerabilities. This is usually the first place urgent work appears.
• Hosting and infrastructure. Where it runs, who pays for it, whether it can be rebuilt if the server disappeared tonight, and whether anything about it is held together by a manual step somebody performs from memory.
• Security posture. Exposed administration screens, how passwords and sessions are handled, credentials sitting in the code, and what an attacker would reach first. Anything urgent here jumps the queue, which is what our security and updates work is for.
• Data and backups. What data exists, where, under what obligations, whether a backup runs, and, the question that matters, whether anyone has ever restored one successfully.
• Tests and deployment. Whether tests exist and still run, and whether a release is a scripted, repeatable thing or an afternoon of somebody being careful.
• Documentation and knowledge. What is written down, what lives only in one person's head, and how much of the system a new engineer can understand without asking anyone.
• Ownership and accounts. Whose name the domain, repositories, hosting, cloud and third-party accounts are in. This one is administrative rather than technical and is frequently the most valuable thing the assessment surfaces.
• Performance and cost. How it behaves under real load, and whether the monthly infrastructure bill is proportionate to what it does.

The deliverable is a written assessment: a prioritised risk list, an honest recommendation, and enough specifics that a different team could act on it. Ask before you commission it whether the document is yours to keep. It should be.

What usually turns up

Most inherited systems are in better shape than their new owners fear, which is worth saying first. Still, the same handful of things turn up again and again.

• Dependencies several years out of date, some with published vulnerabilities that have public exploits.
• No tests, or a test suite that stopped running so long ago nobody remembers it existing.
• A deployment that has only ever happened from one particular laptop, using steps that live in one particular head.
• Credentials, keys and passwords committed into the code, often still valid.
• A backup that runs faithfully every night and has never once been restored.
• One genuinely clever piece of engineering that solves a real business problem and is documented nowhere.
• Accounts registered in the previous supplier's name rather than yours.
• Something quietly broken that nobody noticed: a form that stopped sending six months ago, a scheduled job that has been failing silently, a report nobody reads because it started arriving empty.

None of this means the previous team were bad at their jobs, and a new supplier who frames it that way is selling rather than assessing. It means the software was working, and working software never demands attention until the day it does. The same list would appear in most systems that have been quietly earning their keep for a few years, including ones built by people you would happily hire.

Stabilise first, improve second

The temptation after an assessment is to go straight to the feature you are paying for. Resist it, and be suspicious of a supplier who does not. There is an order that works, and it exists because each step makes the next one safe.

1. Recover ownership. Domains, repositories, hosting, cloud and third-party accounts into your name, with the supplier added as a user you can remove. If the previous team has gone silent, our guide to recovering a website when a developer disappears covers the version where nobody is cooperating.
2. Deal with anything dangerous. Exposed admin panels, unpatched vulnerabilities with known exploits, certificates about to expire, missing backups, credentials in the code. Before any features, in an agreed order.
3. Get it off one laptop. Code into version control you own, a build anyone can reproduce, a staging copy that is not production, and a deployment that is scripted and can be rolled back.
4. Prove a restore. Actually restore the backup somewhere safe and confirm the system comes back. Until that has happened, you do not have a backup, you have a scheduled task.
5. Write it down as you go, while the team is learning it, rather than promising documentation at the end when the budget has run out.

Only then do the improvements start, and they start faster for it, because the team can now change things without holding their breath. That sequence is what adopting software we did not build means in practice: a defined piece of work with a finish line.

How long before a new team is productive on your codebase

Small, safe changes usually start within days. Genuine fluency, the point where a request gets an estimate rather than an intake of breath, typically arrives somewhere between one and three months depending on the size of the system and how much was written down.

Set expectations internally, because this catches people out: the first stretch with a new team will feel slower than the last stretch with the old one. That is not a bad sign in itself. The old team had years of undocumented context, and the new one is buying it back in public, on your budget. What matters is whether the line crosses. If it is still slower after three or four months, and the reasons still sound like archaeology, have that conversation directly.

Handle the handover before you hand in notice

The order of operations matters more than the tone. Before you tell your current supplier you are leaving, know where everything is: which accounts exist, whose name they are in, where the code lives, and what the contract says about who owns it. That is not underhanded. It avoids a situation where the answers become a negotiating position.

Then be straightforward with them. Most agencies handle this professionally and deserve to be asked properly rather than discovered leaving. Ask for one specific thing while the relationship is still civil: a recorded walkthrough of the architecture, half an hour, screen shared. It is worth days of reading code. And where you still hold something they want, use it constructively, because tying the final payment to a documented handover rather than to a date produces a better handover than goodwill does. A cold takeover, where the new team gets a login and no context, costs substantially more than a warm one, and that difference is within your control for about a fortnight.

When rebuilding really is the cheaper answer

Sometimes it is, and a team that never says so is as unhelpful as one that always does. These are the signals that genuinely point at replacement rather than repair.

• The platform is out of support and the upgrade path is a rewrite anyway. When moving from the version you are on to a supported one means rewriting most of it, you are choosing between two rebuilds, one of which leaves you somewhere better.
• Nobody can run it. If it cannot be started on a new machine or deployed reproducibly by anyone alive, you do not have a system you can maintain; you have one you can only pray for.
• The security problems are structural. Patchable holes get patched. Authentication written by hand and written wrongly, or personal data stored in ways that cannot be made compliant, are not patches, they are foundations.
• Every change breaks two other things. High coupling plus no test coverage produces a system where the cost of each change rises rather than falls. That curve does not correct itself.
• The business it models no longer exists. If the concepts baked into the database are the ones you had in 2019 and everything since has been bolted to the side, the mismatch will keep costing you on every single feature.
• The arithmetic says so. When a year of maintaining it approaches the cost of replacing it, the decision has already made itself.

What is not a rebuild trigger: untidy code, an unfashionable framework, or a team that would have done it differently. Almost all working software looks unpleasant to whoever inherits it. If the reasons offered are aesthetic rather than structural, ask which of the six above applies and listen to the answer.

There is also a middle path, overlooked in the rush to pick a side: replace the system piece by piece behind its existing front, retiring old parts as the new ones prove themselves. The business keeps running throughout, you can stop at any point, and it is far less risky than a clean-sheet rewrite. For a public website it is usually the right shape for a redesign or rescue.

Not for you if

The first conversation

Bring what you have: access or an honest account of what you cannot reach, the contract, a list of every account you know about, the problems you already know about, and what you actually want built next. Then ask them these.

1. What exactly will you look at, and what will we get in writing at the end?
2. Is the assessment a fixed price, and is the document ours to keep and to show someone else?
3. Will you tell us if the honest answer is to stay where we are?
4. How do you price the stabilise phase, given that you cannot know its depth yet?
5. What would you do first, and why that?
6. What do you need from our outgoing supplier, and how quickly?
7. Who will own the accounts, the code and the infrastructure when this is done?

The answers tell you most of what you need to know about how the next two years will go. A team that is comfortable saying "we do not know yet, and here is how we will find out without spending your money blindly" is describing the job accurately. That is the one to hire.