Handing over a software project without losing knowledge: a checklist

A software project handover is finished when the new team can change, release and fix the system without calling the old one. Moving the files is the easy part. The hard part is the knowledge in people's heads: why the code is shaped the way it is, which job fails at month-end, and who to call when a supplier's API goes down. Plan the handover as a short project of its own, with a checklist, shadowing in both directions and a support window after the switch.

Why handovers lose knowledge

Handovers happen when you change vendors, bring work in-house, finish a fixed-scope project or lose a key person. They tend to go wrong for the same reasons. The outgoing team is already moving on to other work. Nobody has written down what everyone 'just knows'. And the handover is judged on whether documents arrived, not on whether the new team can do the job.

The cost of lost knowledge builds slowly, then arrives all at once. One bank we worked with ran its core system on a 20-year-old mainframe, and the experienced COBOL engineers who maintained it were retiring. When we moved that system to AWS, the project included documentation, training and a knowledge handover, so the client's own team would own the new platform on completion.

A handover plan in four steps

1. Agree the scope and the people. List what is being handed over, name a lead on each side and set a target date for the switch.
2. Collect and check the assets. Work through the checklist below, moving repositories and accounts into your ownership first.
3. Shadow, then reverse shadow. The new team first watches the outgoing team do real work, then does that work itself while the outgoing team watches.
4. Switch and support. The new team takes full ownership, and the outgoing team stays available for an agreed support window.

Run it like any other piece of work, with each step in your tracker and a short weekly check on progress. A handover without a plan tends to shrink into a pile of documents delivered in the final week.

What to hand over: the checklist

Each item below needs an owner on the outgoing side and a named person on the receiving side. The receiver signs it off when it works, not when it arrives.

Code and its history

• All repositories, with full commit history, branches and tags, in accounts your company owns.
• Open pull requests, with a note on whether to finish or close each one.
• Build and test instructions that a new developer can follow on a clean laptop.

Infrastructure and environments

• Cloud accounts, with ownership and billing in your company's name.
• Infrastructure-as-code definitions, deployment pipelines and environment settings.
• Domain names, certificates, DNS, app store and third-party service accounts, with their renewal dates.

Credentials and access

• Every password, API key and admin login, moved into your own secrets manager and then rotated.
• A list of everyone who had access, with confirmation that leavers have been removed.

Documentation and runbooks

• An architecture overview: the main parts, how they connect and where the data lives.
• Decision records that explain why the important choices were made.
• Runbooks for routine and emergency tasks: releasing, rolling back, restoring a backup, rotating a key and handling the alerts that fire most often.
• Known issues, workarounds and any scheduled jobs that need a person to watch them.

Backlog and business context

• The backlog, with priorities, half-finished work and the reasons behind open decisions.
• Contacts for suppliers, integration partners and the business users who know the processes.
• Contracts, licences and support agreements for third-party tools.

Credentials deserve extra care, because they are also an IP and security risk. Our post on protecting IP when outsourcing covers offboarding and access in more detail.

Shadowing and reverse shadowing

Documents capture what people remember to write down. Shadowing catches the rest. Run it in two stages:

1. Shadowing. The new team watches the outgoing team do real work: a release, a production fix, a sprint planning session. They ask questions and add what they learn to the runbooks as they go.
2. Reverse shadowing. The roles swap. The new team does the work while the outgoing team watches and steps in only when needed. Each time someone has to step in, the gap is written down and fixed.

Give each stage a list of real tasks rather than a fixed number of days. A useful exit test for reverse shadowing is that the new team has released to production, practised a rollback and dealt with a live support issue, all without help.

Keep a support window after the switch

Even a careful handover misses something. Agree a support window, ideally in the contract, during which the outgoing team answers questions and helps with problems. Write down how questions are raised, how quickly they are answered and how much help is included.

Make the window long enough to cover one full business cycle, such as a month-end close or a seasonal peak. Rare jobs and odd edge cases tend to appear then, and you want the people who know them still within reach.

On our project delivery work, handover is part of the definition of done, and after launch there is support while the release settles and an agreed period for fixing defects. For an HR Tech SaaS provider whose payroll platform now covers 40+ regions, we handed over the full source code, workflows and documentation and ran a knowledge handover with the internal engineering team.

Signs a handover is incomplete

• The new team still messages the old team about routine tasks.
• Releases wait for one person who 'knows how it works'.
• Nobody can find a credential, or a bill still goes to the old vendor.
• A scheduled job fails and nobody knew it existed.
• The new team avoids changing part of the code.
• Questions about why something was built a certain way get the answer 'no idea'.

Any one of these means knowledge is still stuck with the outgoing team. Fix it while the support window is open, not after the people who know have moved on.

Where to start

Start planning the handover early, not in the final week. Copy the checklist above into your tracker, give every item two names, one giving and one receiving, and agree the support window in writing before the outgoing team moves on.

If a new partner is taking over, our post on onboarding a software development partner covers the first weeks from the receiving side. If you need a team to take over an existing system, talk to us.