Taking over an existing codebase: establish what must keep working

Record the actual business journeys

Ask staff to demonstrate a normal working day. How does an enquiry arrive, who changes its status and when does an invoice or external notification appear? Include work performed outside the application. A correction spreadsheet may be essential to the process even though it never appears in the repository. This creates a map of the work that must survive the handover.

Select journeys whose failure would have immediate consequences. For each one, describe input, expected output, owner and evidence of completion. Use anonymised or specially created examples. A screenshot shows appearance, but not the records changed behind the screen. Identify the database records and messages associated with the operation as well.

Connect the repository to the running environment

Establish which code version is actually running. A folder called production may be obsolete, while a working local copy may contain unreleased changes. Connect the commit or release identifier, configuration source and deployment method. Unexplained differences are investigation items rather than an immediate reason to replace a server.

Inventory domains, hosting, databases, storage, email, scheduled tasks and external connections. Record an owner and application relationship for each item. A forgotten scheduled task may change records every night without any visible user action. Ask about background work and supplier dashboards as well as the web server. Keep the first inventory focused on the selected business journeys.

Arrange access through identifiable owners

Separate investigation access from permission to change production. Read-only access or an isolated copy is sufficient for many initial checks. Agree who approves wider permissions and how temporary access ends. Do not remove existing operators before demonstrating that the new organisation can release and recover the system.

Account ownership is a continuity issue too. A domain held in a former employee’s personal account requires a different handover from an organisational account with several administrators. Do not collect passwords in the report. Record where access is managed securely, who can restore it and which accounts need replacement later. Permission checks require concrete tests rather than a list of account names.

Use the initial inventory to bound the follow-up investigation: Scoping a software audit: which decision should the evidence support?.

OWASP Application Security Verification Standard ↗

Enable a clean build and test environment

Ask a new developer to build the application using the available instructions. Record missing dependencies, configuration and manual steps. The aim is to reveal knowledge held by only one person, not to measure how quickly someone can guess the setup. Preserve errors and solutions so a second attempt is reproducible.

A useful test environment contains recognisable sample data and creates no real invoices, messages or payments. Check background tasks and external connections too. A different database alone does not make an environment isolated. Demonstrate that the selected sample journey can run safely and that its result is observable. If that is not yet possible, document it as an explicit handover limitation.

Investigate the meaning of important records

Find the person who can explain statuses, dates and identifiers. Similarly named fields may describe different events. A date might mean original entry, last change or business-effective date. A new developer missing that distinction can produce technically valid code that disrupts operations.

Trace one record from entry through reporting. Record the integrations using it and any corrections staff make afterwards. Examine retention needs and whether exports are actually usable. This is not a complete data migration. It is a targeted inventory of the meaning that future changes must preserve. A small sample also does not demonstrate that the entire historical dataset has the same quality.

Read the code through a specific investigation question

An initial code investigation might focus on authentication, error handling or the route that processes an order. State what was inspected and what remains untouched. An older framework is a reason to investigate support and maintenance, not independent evidence that every feature needs rewriting.

Connect findings to the chosen business journeys. A confusing module matters when it delays changes or makes failures difficult to explain. An ownerless dependency may matter for updates. Keep demonstrated defects, plausible risks and missing information distinct. This helps the organisation decide what to investigate or change first without treating a limited review as a verdict on the entire codebase.

Choose a first change with a return path

Do not automatically start with the largest backlog item. A small bounded improvement can demonstrate that the new operator understands development, verification and deployment together. An example could be a clearer error when a reference is missing, provided the relevant path is understood and tested.

Agree how existing behaviour is checked, who reviews the change and how an unwanted effect can be reversed. Returning to old code does not automatically restore records already changed. State whether the change writes data and how that data would be recovered. If the first change reveals unexpected dependencies, revise the next assignment instead of treating the initial estimate as an unconditional promise.

Google SRE: Testing for Reliability ↗

Example: handing over a scheduling application

Illustrative example: a service company takes over a scheduling application after its original developer leaves. The repository contains the website, but the nightly import runs on a separate server. Discovery shows that staff manually add missing jobs each morning. This workaround does not appear in the technical documentation.

The first assignment becomes explaining one import cycle, testing it safely with example files and recording account ownership. A proposal for improved alerts follows afterwards. Evidence includes a traceable sample job, a reproducible build, an import owner and open questions about historical failures. That is useful progress without immediately selling complete replacement.

Request evidence another person can use

A useful handover contains an executable path, not just explanation. Ask a second person to follow the instructions for an agreed operation, such as deploying a test version or locating a failure. Record where guidance was required. This makes transfer testable without demanding that every detail fit one document.

Finish with an inventory of what was received, what was demonstrated and what remains missing. Assign each open item an owner and possible next step. Distinguish operating the system now from understanding every future change. One handover cannot provide the latter certainty. It can establish a repeatable way to record new knowledge, changes and incidents from this point onward.

Turn the explanation into a project decision

Record your assumptions, unknowns and acceptance checks in the matching tool. Use the service guides to discuss delivery and scope.

• Legacy software modernisation ↗
• Software audit ↗

Questions about this topic

Continue with a related question