Back to Blog

Taking Over an Existing Codebase, A Playbook

In this article

• Quick Answer
• What should you do in the first 48 hours after inheriting a codebase?
• What should you do first when you inherit someone elses codebase?
• How do you read into a large codebase without drowning?
• How can you use AI to understand an unfamiliar codebase?
• How do you audit an unfamiliar codebase for risk?
• What is the bus factor and why does it matter?
• How do you get critical knowledge out of the outgoing developer before they leave?
• What belongs in an access and credentials handover?
• Who owns the code, and what should the legal handover cover?
• Why should you stabilize a codebase before adding features?
• What are characterization tests and how do they let you change legacy code safely?
• How do you estimate and prioritise the remediation work?
• What are the red flags that a codebase needs a full takeover rather than a light touch?
• When does taking over a codebase mean you should rewrite instead?
• What does a realistic 30, 60, 90 day plan look like?
• Frequently Asked Questions
• Where Unico Connect fits

Inheriting a codebase is its own discipline, and it is nothing like starting fresh. You are working with decisions you did not make, in a system whose landmines are invisible until you step on one. This playbook is the process we use to take over software safely, understand it, capture what only the outgoing team knows, stabilize it, and only then start shipping features.

What should you do in the first 48 hours after inheriting a codebase?

Before you read a single file, contain the situation. The first 48 hours are about making sure nothing can be lost and nobody can lock you out, not about understanding the code. Freeze non essential feature work so the target stops moving. Clone every repository and confirm you can build from a fresh checkout. Take an ownership inventory of every platform the product touches, the cloud accounts, the domain registrar, the DNS, the app store accounts, the payment and email providers, and the CI system. Then centralise access under accounts you control and rotate the credentials, so a departing developer cannot lock you out or leave a live key behind. Only once the assets are secured and the bleeding is stopped do you move to the audit.

What should you do first when you inherit someone elses codebase?

Set expectations and get access before you get into the code. Accept up front that real productivity is weeks away and full mastery is months away, because pretending otherwise leads to rushed, dangerous changes. Get read access to the repository, staging and production, the issue tracker, monitoring, CI logs, and the cloud console. Then learn what the application actually does and who depends on it, because you cannot judge code you do not understand the purpose of. Only after that do you start reading the code itself, broad to deep.

How do you read into a large codebase without drowning?

Read broad to narrow, not file by file. Start with the shape of the system, the top level components and how they talk, then the building blocks such as the folder structure and the data access patterns, and only then follow one real user request all the way through the code from entry point to database and back. That single end to end trace teaches you more than a week of scrolling. Weight your attention with two signals the git history gives you for free. The files that change most often are the bug magnets, and the modules that generate the most support tickets are where the business actually feels pain, so map both before you form an opinion. Read the database last and carefully, separating the core entity tables that hold the domain from the configuration and lookup tables that just tune it, and generate a diagram from the live schema so the data model is visible rather than imagined.

How can you use AI to understand an unfamiliar codebase?

This is what has genuinely changed in 2026. A large language model working in a read only mode can do code archaeology across an entire repository far faster than a person reading top to bottom, tracing how a feature flows, flagging dead code, summarising a module, and mining the git history for why a change was made. We use it to produce a first draft of the architecture map, a data flow for the riskiest paths, and a ranked list of hotspots, then a senior engineer verifies and corrects it, because the model is a fast reader, not the final authority. The discipline that makes this work is keeping a curated context file in the repository that records what we have learned, so each session builds on the last instead of starting cold. Used this way, AI turns the slowest part of a takeover, the first read, from weeks into days, without lowering the bar on what a human signs off.

How do you audit an unfamiliar codebase for risk?

Run a structured audit rather than wandering through files. Map the architecture first by tracing entry points and call paths, counting the databases and external services, and sketching the data model so you can see the domain core. Then use git history as a guide. The files that change most often are usually the bug magnets, so a churn analysis points you straight at the risky areas. From there, work through security, dependencies, tests, and documentation. The point of the audit is to replace vague dread with a prioritized risk register you can act on.

What is the bus factor and why does it matter?

The bus factor is the number of people who would have to leave before a project is in serious trouble because the knowledge left with them. It matters enormously for an inherited system, because low bus factor is exactly why takeovers are risky. Research on popular open source projects has found that around 65 percent of them have a bus factor of two or fewer, meaning the knowledge sits with just one or two people. When you inherit code, part of the job is measuring this and then raising it, by writing down what is currently in someones head.

How do you get critical knowledge out of the outgoing developer before they leave?

Treat knowledge transfer as capturing the why, because the how is recoverable from the code and the why is not. Run structured, recorded sessions that walk through the architecture, the deployment pipeline, and an open question and answer. Separate the explicit knowledge that lives in documents and specifications from the tacit knowledge that only exists in someones memory, such as why a strange workaround exists or which part of the system is fragile. The tacit knowledge is the whole reason to do live sessions while the team is still around. Write all of it into searchable notes as you go.

What belongs in an access and credentials handover?

Inventory every account, key, cloud project, domain, and certificate the system depends on, then rotate the secrets and remove any personal access that belonged to the departing team. A handover that leaves a former developers personal token in a config file, or a shared password nobody has changed, is a breach waiting to happen. This is also the moment to scan the git history for secrets that were committed at some point, because they stay in history even after they are deleted from the current files.

Beyond credentials, ask for the full handover package while you still have the outgoing team. That means the source for every part of the product, the design files, the infrastructure and access map covering DNS, certificates, backups, and the CI and deployment pipeline, the database backups and migration scripts, and the documentation such as it is. Get one honest debrief where they walk you through the deployment end to end, because the pipeline is where undocumented steps hide.

Who owns the code, and what should the legal handover cover?

This one surprises founders, so confirm it early rather than assume it. In many jurisdictions the person or company that wrote the code owns the copyright unless a contract explicitly assigned it to you, so check that your agreements contain a clear IP assignment rather than relying on the idea that paying for work automatically transfers ownership. Confirm the licence position of every third party and open source dependency too, since a restrictive licence buried in the tree can constrain what you are allowed to do commercially. Where the original team is a company you depend on, a source code escrow arrangement, which releases the code and build instructions to you if they go out of business or abandon the project, is worth discussing. This is general guidance rather than legal advice, so run the specifics past counsel in your own jurisdiction, but raise it during the handover while there is still goodwill to get it right.

Why should you stabilize a codebase before adding features?

Because changing code you cannot test, on a system that does not build reliably, is how takeovers turn into disasters. Michael Feathers defines legacy code simply as code without tests, and that framing is the key to the whole playbook. Before you touch anything risky, get a one step local setup working, get a reliable green build in CI, add basic observability so you can see what the system is doing, and wrap the code you are about to change in characterization tests. Only once you can change the system safely do you start delivering features on top of it.

What are characterization tests and how do they let you change legacy code safely?

A characterization test captures what the code currently does, correct or not, so that any change you make that alters that behaviour shows up immediately. You are not asserting what the code should do, you are pinning down what it does today. Feathers describes the process as finding the change point, finding a seam where you can insert a test, breaking the dependencies that make testing hard, capturing current behaviour, and only then making your change. It is the safety net that lets you refactor code you did not write and do not fully trust yet.

How do you estimate and prioritise the remediation work?

Turn the audit into a ranked plan rather than a wish list. For each problem, estimate the remediation cost as the engineering days to fix it, and weigh that against the ongoing drag it causes, the interest you pay every sprint for leaving it. A fix that is cheap and removes a constant tax gets done first. Then score the risk of each item on likelihood and impact, and treat the low likelihood but catastrophic items, such as a single unpatched auth flaw, as urgent even when they rarely fire. The output is a prioritised risk register where every item has an owner, an effort estimate, and a risk score, so the sequence of work is a decision you can defend rather than whatever felt scary that week.

What are the red flags that a codebase needs a full takeover rather than a light touch?

Some signals tell you the inherited system needs a serious intervention, not a few tweaks. Watch for one fix reliably creating two new bugs, core flows that stay unstable after several rounds of cleanup, nobody being able to explain the architecture or the release process, no control over who can access or deploy the system, dependencies that are years past end of life, and secrets or known vulnerabilities sitting in the repository. A cluster of these means the foundation, not the surface, is the problem. Even then the answer is rarely a big bang rewrite. It is a planned, staged intervention, and the choice between improving in place and replacing incrementally is exactly what the scorecard in our rebuild vs refactor guide is built to settle.

When does taking over a codebase mean you should rewrite instead?

Almost never as your first move. The default is to stabilize and improve incrementally, and to use the strangler fig pattern for any larger structural replacement so the system stays live. A rewrite is only justified when the platform is genuinely at end of life, the architecture is fundamentally wrong for where the business is going, the project has been abandoned with no path forward, or the system is small enough to redo faster than it would take to understand it. If you are weighing that call, our guide on rebuild vs refactor has a scorecard for it.

What does a realistic 30, 60, 90 day plan look like?

In the first 30 days you orient and audit. Get all access, run the app locally, complete the full audit battery, finish knowledge transfer and the credentials handover while the old team is still reachable, produce an architecture map and a prioritized risk register, and ship one tiny safe fix to prove the pipeline works end to end.

In the next 30 days you stabilize and start contributing. Get CI green, add observability, wrap the highest churn and highest bug modules in characterization tests, remediate the critical vulnerabilities and rotate secrets, and ship small features with decreasing supervision while you begin reviewing other changes.

By days 61 to 90 you take ownership. Own deployments and incident response, take on larger scoped work, begin any planned modernization using the strangler fig pattern for structural changes, and deliver a clear go forward plan for each major area, whether that is refactor, replace, or leave alone.

Frequently Asked Questions

Where Unico Connect fits

Taking over other teams code is a large part of what we do. If you have inherited an MVP that needs rescuing or scaling, or an app built on Lovable or another no-code stack, we run this exact playbook. We audit the real state first, capture what the previous team knows, stabilize the build and the security surface, and then either refactor in place or migrate incrementally onto a system you own. If the audit shows the foundation itself is the problem, our rebuild vs refactor guide walks through that decision, and our Supabase RLS security checklist is the security audit we run on Supabase projects.