The one developer who knew the system left: breaking key-person dependency

If only one person understands your software, the real risk is not that they leave. It is that nobody treated it as a risk until they did. The measure has a name, the bus factor: how many people would have to disappear at once for the project to stall. For most companies the answer is one. The useful part is that the fix is not "hire a second developer who knows the same things." It is getting the knowledge out of one head and into a readable part of the system. Three things need to change hands: access to the running system, the reasoning behind decisions already made, and the steps for routine work. You already have the code. The code was never the missing piece.

The numbers say this is the norm rather than the exception. Avelino and colleagues analysed 133 popular GitHub applications and found a bus factor of 1 in 46% of them and a bus factor of 2 in another 28%. Three quarters of those projects would be orphaned by one or two departures, and these are open projects that anyone can read and contribute to. There is no reason to assume closed corporate codebases do better. Stack Overflow's 2024 developer survey found 61% of respondents spend more than half an hour a day searching for answers, and 30% say knowledge silos cost them productivity ten or more times a week. The loss does not arrive in one lump when someone resigns. It is paid out daily in small amounts.

The dependency is not in the code

Code is readable text. Give a competent developer enough time and they will work it out. What they cannot work out lives somewhere else.

First, access. Which account the domain is registered under, which card the cloud invoice runs through, whose phone receives the two-factor code for the app store account. None of that is written in the repository. Second, the reasoning behind decisions: why this database, why a direct call instead of a queue, why that column is still a text field. Code shows you the outcome of a decision, never the reason for it. Without the reason, a new team either refuses to touch the thing or reopens a door that was deliberately closed a year ago. Third, the routines. How a release goes out, how it gets rolled back, how a restore is tested, which screen you look at first when the alarm fires at three in the morning. This last group is almost never written down, because for the person doing it, it stopped requiring thought years ago.

Start with access, not with code

Transferring access is the easiest part of a handover and the most consistently postponed. It takes an afternoon. It is also the part that gets expensive when you delay it, because once the relationship sours there is no recovering it. The inventory should cover:

• Domain registration, DNS management and certificate renewal
• Cloud account root user, billing and identity management
• Ownership of the code repository organisation and its admin rights
• The CI/CD pipeline and the secrets stored inside it
• App store developer accounts and signing keys
• Payment provider, email and SMS services
• Monitoring, alerting and error tracking tools
• Third-party API keys and integration accounts
• Database administrator access and the backup store

Two rules while you fill that list in. Every account belongs to a company email address, and every second factor lands on a channel the company controls. A domain registered to someone's personal Gmail, or a store account tied to one employee's phone, is not a technical gap. It is commercial leverage held by an individual. When someone does leave, rotate every shared secret; disabling their user account does nothing for an API key they had a copy of. Keeping those keys out of the codebase in the first place is its own subject, covered in our note on secrets management.

Write down why, not what

Michael Nygard's 2011 post "Documenting Architecture Decisions" gave this problem the most practical answer anyone has produced since: the architecture decision record. The mechanics are plain. When a significant decision is made, you add a numbered text file to the repository with five headings. Title. Status, meaning whether it still holds or was superseded. Context, meaning the constraints in place that day. Decision. Consequences, meaning what it cost you. It fits on one page, it lives next to the code, and it goes through review with the code.

What separates an ADR from the 60-page architecture document nobody opens is timing and authorship: it gets written at the moment of the decision, by the person making it. Nobody is going to sit down and retroactively document forty decisions, and nobody needs to. For an existing system the practical starting point is to ask the team which ten decisions would surprise a newcomer who asked "why was it done this way," then write only those. Two days of work, and it is the document that earns its keep at the next handover.

Runbooks for the work that repeats

A runbook is a short document someone can follow step by step the first time they do a task. The minimum scope is predictable: how a release ships, how it rolls back, how a restore from backup is performed and when it was last actually tested, whether certificate renewal is automatic or manual, how a new environment variable gets added, and the first three steps for each known alert. It does not need to be long. It needs to be correct and current.

There is only one valid test for a runbook: can somebody else follow it while the author is out of the room. Run that test once a year on purpose, and fold the result back into the document. If you have never restored from a backup, you cannot claim to have backups. That line is a cliché and plenty of companies still learn it during a real incident. How the first hours of one should be handled is covered in our incident response piece.

Measure the bus factor instead of guessing it

Your git history already holds the answer. Looking at authorship over the last year for one critical module tells you most of what you need:

git log --since="12 months ago" --format='%an' -- src/payments/ | sort | uniq -c | sort -rn

Run it separately for payments, authentication, billing and the integration layer. If the overwhelming majority of the last twelve months of changes in a module carry one name, that module belongs to that person, and the fact that others touched the directory occasionally does not change it.

There is a blunter test than measurement, and it works better. Call it the silence drill. For two weeks, the person in question answers no technical questions at all; they watch and take notes. Every point where the team gets stuck goes on the list of gaps you need to close. Holiday season is a natural opportunity, on one condition: the phone has to be genuinely off.

Documentation is a multiplier, not overhead

Documentation stays in the "if we get time" pile at most companies because the return is invisible. DORA's research on documentation quality put a number on that return, and the gap is wider than teams expect. Among teams with above-average documentation quality, continuous integration produced roughly a 750% lift in organisational performance, while the same practice in teams with below-average documentation stayed in the double digits. Same practice, same tools, different outcome. The mechanism is easy to guess: an undocumented practice gets applied partially, applied inconsistently, and abandoned the first time the team is under pressure. It is also a decent explanation for why technical debt keeps accumulating in some teams and not others.

Can AI assistants close the gap?

Partly. Point a language model at the codebase, ask what a service does, and you will get a reasonable summary. That genuinely shortens a new developer's first week. What the model cannot supply is exactly what is missing: why the decision was made. Reasoning that is absent from the code is absent from the model too, so it infers, and it presents the inference in a confident voice. DORA's 2024 report estimates that a 25% increase in AI adoption corresponds to about a 7.5% improvement in documentation quality. The cost of writing documentation is coming down. Commissioning it and verifying it is still human work, in the same way that reviewing AI-written code is.

If an agency built it

Key-person dependency also happens outside your company, and that version is worse because you hold less leverage. Put four clauses in the contract. The repository lives in your organisation and the vendor is invited into it. Production runs in your cloud account and the invoice comes to you. The deliverables list includes decision records and runbooks alongside working software. Termination or contract end triggers a handover window of at least thirty days plus a live handover session. Ownership and escrow arrangements are covered in source code ownership, and the maintenance side in our note on the support contract.

Three things you can do this week, and together they will not consume a full developer day. Build the access inventory as a table and answer two questions on every row: who owns this account, and where does the recovery code land. Pull the authorship distribution from git for your three most critical modules. Write the next architecture decision into a one-page file on the day it is made. At Wedevit we map key-person dependencies in systems you are taking over or handing off, plan the access and documentation transfer, and set up the minimum structure your team needs to keep it current. All of it runs remotely.