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 takes a different discipline from starting fresh. You are working with decisions you did not make, in a system whose landmines stay invisible until you step on one. This playbook is the process we use to take over software safely. We learn what the system does, 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?

Contain the situation before you read a single file. The first 48 hours are about making sure nothing can be lost and nobody can lock you out, and understanding the code is a job for later. 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, including 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. The audit starts only once those assets are secured and the bleeding has stopped.

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 does and who depends on it, because you cannot judge code until you know what it is for. Reading the code itself comes after that, working from broad to deep.

How do you read into a large codebase without drowning?

Work from broad to narrow and resist reading 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. Once you have those, 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 you already have for free. The files that change most often in the git history are the bug magnets, and the modules that generate the most support tickets are where the business feels pain, so map both before you form an opinion. Read the database last and carefully. Separate 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 you are working from the real data model.

How can you use AI to understand an unfamiliar codebase?

AI is the biggest change to this work 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. It can trace how a feature flows, flag dead code, summarise a module and mine 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. A senior engineer then verifies and corrects that draft, because the model is a fast reader and the final authority stays with a person. What makes this work is a curated context file in the repository that records what we have learned, so each session picks up where the last one stopped. 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 instead of 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. Files that change most often usually attract the most bugs, so a churn analysis points you straight at the risky areas. From there, work through security, dependencies, tests and documentation. The audit should turn vague dread into 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 a lot for an inherited system, because a low bus factor is what makes takeovers 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. Part of inheriting code is measuring that number and then raising it, which means writing down what currently lives 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. That tacit knowledge is the reason to hold 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 former developers personal token left in a config file, or a shared password nobody has changed, gives an attacker an easy way in. Scan the git history for secrets at the same time, because a secret committed at some point stays in history even after someone deletes it 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, and the database backups and migration scripts. The package should also include an infrastructure and access map covering DNS, certificates, backups and the CI and deployment pipeline, plus whatever documentation exists. 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?

The ownership question surprises founders, so confirm it early. 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 and do not assume that paying for the 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. If the original team is a company you depend on, it is worth discussing a source code escrow arrangement, which releases the code and build instructions to you if they go out of business or abandon the project. This is general guidance and should not be read as legal advice. Run the specifics past counsel in your own jurisdiction, and raise the subject during the handover while there is still goodwill to get it right.

Why should you stabilize a codebase before adding features?

Changing code you cannot test, on a system that does not build reliably, is how takeovers turn into disasters. Michael Feathers defines legacy code as code without tests, and the rest of this playbook follows from that definition. 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. Start delivering features on top of the system only once you can change it safely.

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. The test makes no claim about what the code should do. It pins down what the code 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. With that safety net in place you can refactor code you did not write and do not fully trust yet.

How do you estimate and prioritise the remediation work?

Turn the audit findings into a ranked plan. 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. You end up with 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?

Signs that an inherited system needs serious intervention include 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. When several of these show up together, the problem sits in the foundation. Even then the answer is rarely a big bang rewrite. It is a planned, staged intervention, and choosing between improving in place and replacing incrementally is 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 justified only when the platform is 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, run your system through our rebuild vs refactor scorecard.

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 and 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.

The next 30 days are for stabilizing and starting to contribute. Get CI green, add observability, and wrap the highest churn and highest bug modules in characterization tests. Remediate the critical vulnerabilities, 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, and begin any planned modernization, using the strangler fig pattern for structural changes. Close the period with 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.