What I do in my first week on an unfamiliar codebase
Joining an existing codebase is a skill nobody teaches. You're expected to be productive in a system thousands of decisions deep, and none of those decisions are written down.
I've joined a lot of codebases — as an employee, as a subcontractor, as a tech lead. This is what I do in the first week.
1. Run it before I read it.
Day one, I get it building and running locally. The setup is the most honest documentation there is: every step the README forgot is a place where the team's knowledge lives in someone's head.
2. Follow one request, end to end.
I pick a single real user action and trace it from the button to the database and back. One vertical slice teaches more than reading every folder. This is also where AI tools genuinely earn their keep — "walk me through how this request flows" beats reading top to bottom, as long as I check the answer against the code.
3. Read the tests before the code.
Tests show what the team thinks matters. The parts with no tests show what nobody wants to touch — and that's usually where the first bug report comes from.
4. Read recent pull requests, not just the wiki.
The wiki says how the team wants to work. The last few weeks of merged PRs show how it actually works: what gets pushed back on in review, what gets merged without a comment.
5. Ship something small in week one.
A typo fix, a missing validation, a flaky test. The change doesn't matter — going through the real review, CI and deploy once teaches the process faster than any onboarding doc.
The honest nuance: don't refactor anything in week one. The strange code almost always has a reason you don't know yet — a customer, an incident, a constraint that never made it into a comment. Understand it first. Improve it in week three.
The goal of the first week isn't to be productive. It's to find out where the real knowledge lives.
What's the first thing you do when you join a new codebase?