---
title: "Taking Over a Codebase From Another Agency"
description: "How to move software from one development team to another: what to secure before giving notice, how to grade the codebase you inherit, and how to run the first weeks."
url: "https://codesagelabs.com/resources/taking-over-an-existing-codebase"
type: "guide"
author: "Anjula Paulus"
published: "2026-10-16"
modified: "2026-10-16"
publisher: "Code Sage Labs"
---

# Taking Over a Codebase From Another Agency

By Anjula Paulus, Founder and software engineer at Code Sage Labs. Published 2026-10-16, last updated 2026-10-16.

Changing development teams is ordinary and usually survivable. What makes it expensive is sequence: access and ownership are easiest to arrange while the relationship is still cordial, and hardest once notice has been given. This guide covers what to secure first, how to tell a recoverable codebase from a genuinely unrecoverable one, and what a competent incoming team should and should not do in the first month.

## Key takeaways

- Confirm ownership and access before you give notice, not after.
- Grade the codebase on build, tests, deployment and secrets before planning anything.
- Most inherited systems are recoverable; the usual blocker is undocumented operations.
- A new team that starts with a refactor is managing its own discomfort, not your risk.
- Budget a stabilisation period before the first feature; skipping it costs more later.

## Terms used in this guide

The handover conversation uses these words constantly and rarely defines them.

- Takeover — a new team assuming responsibility for software someone else built.
- Handover — the transfer itself: code, access, knowledge and operational responsibility.
- Stabilisation — the first phase after a takeover, spent making the system buildable, deployable and observable rather than adding features.
- Tribal knowledge — what the outgoing team knows and has never written down; the most commonly lost asset.
- Bus factor — how many people can leave before nobody understands the system.
- Runbook — written instructions for operating the system, including what to do when it breaks.
- Dead code — code that still exists but no longer runs; dangerous mainly because nobody is certain which it is.
- Build reproducibility — whether a new engineer can produce a running system from the repository alone.

## Before you give notice

Access tends to end with the relationship, sometimes abruptly and sometimes through simple inattention once the supplier has no commercial reason to help. Everything in the list below is normal to request at any point in a healthy engagement, and much harder to obtain afterwards. Doing it early is not an act of bad faith; it is the same diligence you would apply to any single point of failure.

If your contract already puts repositories, cloud accounts and domains in your own name, most of this is already done and the takeover is an administrative exercise. If it does not, that is the first thing to correct, ideally as a normal contractual tidy-up rather than as an opening move in a separation.

- Administrative ownership of repositories, with full history
- Root or owner access to cloud accounts, not a delegated user
- Domain registrar and DNS control
- App store and developer accounts in the company's name
- Third-party service accounts, billing and API credentials
- A current database backup you have restored yourself at least once
- Analytics, monitoring and error-tracking accounts

## What to collect from the outgoing team

Ask for this while there is still an incentive to co-operate, and ideally make a short paid handover window part of the exit rather than an unpaid favour. A supplier being paid for two days of questions answers them; a supplier doing it for nothing answers the first one.

- Build and local setup instructions that a new engineer can follow unaided
- Deployment steps, including migrations, approvals and rollback
- An environment and service inventory with owners and costs
- The secrets, and where they are stored
- Architecture notes and the reasons behind the decisions that look odd
- Known defects, deferred work and unsupported paths
- Scheduled jobs, integrations and anything that runs on a timer
- A list of the parts only one person understands

## Grade the codebase before planning anything

An incoming team should assess the system against concrete signals rather than aesthetic judgement, because a new team's instinctive reaction to unfamiliar code is that it is bad. Each line below gives one signal at three grades: green is fine, amber needs work in the first weeks, red needs work before anything else happens.

- Build — green: one documented command produces a running system. Amber: it works with undocumented steps. Red: nobody present can build it.
- Tests — green: meaningful coverage of critical paths, passing. Amber: some tests, unreliable. Red: none, or all disabled.
- Deployment — green: an automated pipeline anyone authorised can run. Amber: manual but written down. Red: one person's laptop.
- Secrets — green: in a managed store, rotatable. Amber: in configuration files under restricted access. Red: in the repository, or unknown.
- Infrastructure — green: defined in code. Amber: manual but inventoried. Red: undocumented resources discovered by billing.
- Dependencies — green: current and patched. Amber: behind but supported. Red: on an unsupported runtime or framework version.
- Data model — green: documented, with migrations in version control. Amber: readable but undocumented. Red: schema changed by hand in production.
- History — green: full repository history transferred. Amber: history exists but is partial. Red: a single initial commit of a zip file.
- Observability — green: logs, metrics and alerts with an owner. Amber: logs only. Red: you learn about outages from users.
- Documentation — green: a runbook someone has followed. Amber: a stale wiki. Red: one person's memory.

## The first four weeks

The purpose of the first month is not features. It is to reach the point where a change can be made and released safely, because until then every feature is a gamble and every estimate is a guess. Resist the pressure to show immediate delivery; a visibly stabilised system is a better first month than a feature shipped through a process nobody trusts.

- Week one — reproduce the build locally, inventory services and accounts, restore a backup into a test environment
- Week one — rotate every credential the outgoing team held
- Week two — get a deployment through the pipeline, however small, and document what it took
- Week two — add monitoring and alerting if they are missing, so failures are visible before users report them
- Week three — write characterisation tests around the business rules nobody can explain
- Week three — produce the system map and risk register, with the red items from the grading named
- Week four — make one small, real change end to end, and only then estimate anything larger

## What the new team should not do first

A new team's early suggestions are strongly biased towards the unfamiliar being wrong. Some of the suggestions below will be right eventually; none of them is right in month one, when nobody yet knows which behaviour is accidental and which is a business rule someone depends on.

- A broad refactor before there are tests to prove nothing changed
- A framework or language upgrade while the deployment path is still unproven
- Deleting code that looks unused without checking whether it runs
- Reorganising the repository, which destroys the blame history you will need
- Replacing a working third-party service with a preferred alternative
- Proposing a rewrite before the system has been operated for a month

## A decision rule

Apply these in order after grading the codebase, and stop at the first that matches.

- Rule 1: if the build or the deployment path is red, fix those before anything else, including urgent features; without them nothing can be shipped safely anyway.
- Rule 2: if secrets are red, rotate everything the outgoing team could access, on day one, regardless of how the relationship ended.
- Rule 3: if two or fewer signals are red and the data model is green or amber, continue with the existing system; it is recoverable and a rewrite would discard working business rules.
- Rule 4: if the data model is red, deal with that specifically rather than concluding the whole system must be replaced.
- Rule 5: if the runtime is unsupported and cannot be upgraded in place, plan an incremental replacement behind a boundary rather than a full rewrite.
- Rule 6: only consider a rewrite when the system cannot be built, cannot be deployed and cannot be understood after a month of genuine effort, and then preserve the business rules before writing any new code.

## Questions

### What should I get before changing development agencies?

Administrative ownership of repositories with full history, owner access to cloud accounts, domain and DNS control, app store and third-party accounts, the secrets, a database backup you have restored yourself, and the deployment instructions. Arrange these before giving notice, because access often ends with the relationship.

### How long does it take a new team to take over a codebase?

It depends on the state of the build, deployment, tests and documentation rather than on the size of the code. Grade those first. A well-documented system can be operated within weeks; one where nobody can build or deploy it needs that fixed before any other estimate means anything.

### Should a new team rewrite inherited software?

Almost never as a first act. A new team's instinct is that unfamiliar code is bad, and a rewrite discards business rules nobody has written down. Rewrite only after the system has been operated for a month and the specific blocker is understood.

### The previous agency will not hand anything over. What now?

Work from what you control: the running system, the domain and cloud accounts if they are yours, and any backups. Rebuild the deployment path from the running environment, rotate every credential, and treat the recovery as the stabilisation phase. Then correct the ownership terms so the next transition is administrative.

## Related

- [See how we take over existing software](https://codesagelabs.com/services/software-modernisation)
- [All guides](https://codesagelabs.com/resources)

*Source: [https://codesagelabs.com/resources/taking-over-an-existing-codebase](https://codesagelabs.com/resources/taking-over-an-existing-codebase) — Code Sage Labs, Colombo, Sri Lanka. Contact: hello@codesagelabs.com*