Developer Onboarding for a Legacy Codebase
What to hand a new developer on day one, and a first two weeks that teaches the legacy system instead of touring it.
Developer onboarding on a legacy codebase is mostly a scavenger hunt. The new person clones the repo, reads a README that describes the setup and not the system, and then spends two weeks collecting oral history. The code will tell them what it does. It will not tell them why it is shaped that way, or which part is safe to touch.
What to hand them on day one
Four things. If you only have time for one, make it the third.
The packet
- 1
The job of the system, in plain language
What it is for, who it serves, and what "broken" looks like. A diagram of every box can wait.
- 2
The constraints that still bite
The ones that make a simple change hard. A compliance rule, a customer who depends on a quirk, a job that must not run twice.
- 3
The last incident that still matters
Not the archive. The outage whose lesson would change what they do this month.
- 4
A person, for a specific area
"Ask Priya about billing" is onboarding. "Ask the team" is a queue.
The first two weeks
One path, one change, one conversation
- 1
Trace one real path
Pick a request a customer actually makes. Follow it from the entry point to the write, including the failure branch. Skip the tour of every service.
- 2
Ship a small change in an existing path
A bug or a small extension, not a new feature. Changing something that already exists teaches the constraints. A greenfield task teaches the framework.
- 3
Walk the weird part with someone who was there
History is the hard part of a legacy codebase, and it is the part the code is worst at explaining. Why this lock exists. Why the old provider is still in the config. Write down the answer while you are both looking at it.
What wastes the first month
- A wiki backfill as the onboarding project. They will document the current code, which they can already read, and miss the decisions.
- A meeting that walks every service for an hour. They will remember the first two.
- "Just read the code." They will, and they will invent a plausible reason for every oddity. Some of those reasons will be wrong, and they will build on them.
Onboard against the knowledge you already have
Prodigent gives a new developer the systems, decisions, and incidents in context, instead of a list of people to interview.
Try Prodigent free