Onboarding a new developer to a codebase without a wiki

Written By: BrainSoft In Engineering

The repo has no wiki. The README is three lines long and one of them is wrong. The person who built half of it left two years ago. This happens on most projects we inherit, and it is not actually a blocker: the code, the git history, and the test suite carry more truth than any wiki page that stopped being updated in 2021.

You will onboard by reading the entry points, running the app locally, mining git history for decisions, and pairing on one small real change in the first two days. Below is the exact order I walk a new developer through, with the commands I actually type.

Start at the edges, not the middle

Do not open a random service file and start scrolling. Find where the program begins and where requests enter. Those files name the frameworks, the config loading, the middleware, and the wiring, which is the map you are missing.

git ls-files | grep -Ei 'main|app|server|index|routes|urls' | head -30

Read those files top to bottom. Then follow one request or one command end to end, out loud, writing the path on paper. You will forget names; the paper keeps the shape.

Get it running before you understand it

A codebase you cannot run is a codebase you cannot reason about. Get the app booting and the tests executing on day one, even if half of them fail. Failures are documentation: they tell you what the environment expects.

1. Clone, then look for lockfiles, Dockerfiles, and CI config to learn the real toolchain versions.
2. Copy the example env file and fill it from the dev secrets store, not from a colleague's memory.
3. Run the test suite and save the output. Note which tests fail before you touch anything.
4. Start the app and hit one endpoint or screen. Confirm you can see data move.

docker compose up -d
npm ci && npm test 2>&1 | tee /tmp/baseline.txt

Keep that baseline file. It is the difference between a real regression and a pre-existing mess. If the environment is genuinely broken and nobody can fix it in an afternoon, that is often where get in touch comes up, because a broken dev setup burns a week per hire.

Mine git history and tests for the why

Wikis record intent; git records what actually happened. When you hit a strange conditional or a retry loop, ask the history instead of guessing.

git log --oneline --follow -- path/to/odd_file.py | head -20
git log -S 'retry_count' --oneline --all

The pickaxe search (-S) finds the commit that introduced a string, which usually carries the ticket number and the reason. Tests do the same job from the other side: a test named rejects_expired_token is a requirement someone wrote down. Read the test names in a module before you read the module.

• Blame the lines that look defensive, then read the commit message.
• Search for TODO and FIXME comments; they mark known edges.
• Find the oldest and newest files by date to see what is stable and what is churning.

Ship one small change with a reviewer

Reading builds a model; shipping tests it. Pick a real but small ticket, ideally one that touches config, logging, or a validation branch. Pair for the first hour, then let the new developer drive alone and open a pull request.

Review the diff together and use it as a tour: why this layer, why this naming, what would break here. Ask them to write a short note in the repo, not in a separate wiki, covering the setup steps that were not obvious. That note lives next to the code and gets updated by the next person. For teams that need help stabilising undocumented systems, that is part of our services.

Frequently asked questions

#Engineering