The first time I joined a big company, I tried to read the whole codebase.
I lasted about a day and a half before realizing it was hundreds of thousands of lines and I'd understood approximately none of it. I felt stupid. I was just doing it wrong.
I've since onboarded to a lot of codebases, and I've got it down to about a week — lost to shipping a real change. Not by reading everything. By reading almost nothing, in the right order. Here's the exact playbook.
You onboard to a new codebase fast by refusing to understand all of it. Instead: get it running first, trace one real user request end to end, ship a tiny change in week one to learn the workflow, and map the territory through tasks instead of cover-to-cover reading. The goal of week one isn't comprehension — it's orientation plus one shipped change. Understanding comes later, through doing.
The single biggest onboarding mistake is treating a codebase like a book you read front to back. It isn't. It's a city you learn by living in, one neighborhood at a time.
No senior engineer on your new team understands the whole thing either. They understand the parts they've worked in and have a rough map of the rest. That's the actual target — not total comprehension, which doesn't exist, but a useful mental map plus deep knowledge of wherever you're currently working.
So I gave myself permission to be ignorant of 95% of the code, on purpose. That permission is what makes the first week productive instead of paralyzing. Letting go of the need to understand everything is, oddly, one of the markers I describe in the brutal truth about becoming a senior developer.
Nobody understands the whole codebase. Your job in week one isn't to understand it — it's to get oriented and ship one small thing.
Before I read a single line for understanding, I get the thing running locally. This is non-negotiable, and it's where I spend my first day or two.
Why first? Because a codebase you can run is a codebase you can experiment with. You can change something, see what happens, break it, learn. A codebase you can only read is a museum behind glass.
Getting it running is also the best possible map of the project's real complexity. Every undocumented environment variable, every "oh you also need this service," every broken setup step — that's you learning the system's true shape, the parts the README politely omits.
And there's a hidden gift here: fixing the setup docs is your first contribution. I keep a notes file of every step that wasn't documented, and my first PR is often updating the onboarding guide. It's genuinely useful, it's low-risk, and it teaches me the contribution workflow before I touch anything scary.
My day-one checklist:
Once it runs, I pick one real thing the app does and trace it from the very front to the very back.
Not a survey of every feature. One. Usually the most central one — a login, a checkout, whatever the app is fundamentally for.
I follow it like a detective. The user clicks here. That calls this. Which routes to that. Which queries this. Which returns up through there. I literally write the path down as a numbered list, file by file, function by function.
This one exercise teaches more than a week of random reading, because it shows me the skeleton — how the layers connect, where the boundaries are, what the conventions look like in practice. Once I've seen one request flow through every layer, every other feature is just a variation on a shape I now recognize. It's the same systems-thinking muscle I built when I learned system design without a CS degree. Tracing a real request is also the technique Google's web.dev recommends for understanding how a running application actually behaves, rather than how its docs claim it does.
// the kind of trace I write for myself, by hand:
// 1. POST /checkout -> routes/checkout.ts
// 2. validateCart() -> services/cart.ts
// 3. chargePayment() -> services/billing.ts
// 4. createOrder() -> db/orders.ts
// now I know the spine. everything else hangs off it.
By midweek, I stop studying and start shipping. The goal: one small, real change merged before the week is out.
Not because the change matters much. Because the process of shipping it is the fastest teacher of how the team actually works. Shipping one tiny change forces me to learn:
That entire workflow — the real machinery of being productive on the team — is invisible until you push something through it. A one-line fix teaches it as well as a thousand-line feature, and far faster.
I deliberately pick the smallest real task available. A tiny bug, a missing validation, a copy fix. The point is the round trip, not the impact.
| Week-one move | What it actually teaches |
|---|---|
| Get it running | The system's true complexity |
| Fix the setup docs | The contribution workflow, safely |
| Trace one request | The architectural skeleton |
| Ship a tiny change | How the team really ships |
| Keep a questions log | Where to look next |
A few supporting habits hold the whole playbook together.
I keep a running questions log. Every "wait, why is this like this?" goes in a file. Some I answer myself later; the rest become great questions for my onboarding buddy. Batching questions respects everyone's time and gives me a paper trail of my own learning.
I ask "where," not "what." Instead of "how does billing work?" (an essay), I ask "where does the billing code live?" (a pointer). Pointers are cheap for teammates to give and let me explore on my own. I'm collecting map coordinates, not lectures.
I read tests to learn intent. When I want to understand a module, I read its tests before its code. Tests show what it's supposed to do, in small examples, which is often clearer than the implementation.
I lean on tooling to navigate. Good editor search, jump-to-definition, and AI assistants that can explain an unfamiliar file on demand turn a scary 2,000-line module into something I can ask questions about. The faster I can navigate, the faster the map fills in.
I expect to feel lost, and don't panic about it. Feeling lost in week one isn't a sign I'm failing. It's the normal texture of onboarding. The map fills in fast once I stop demanding it be complete on day one.
Q: What if the codebase has no documentation at all? Then the running app is your documentation, and your trace of one request becomes even more valuable. Read tests for intent, ask "where" questions, and write the docs you wish existed as you go — that's a gift to the next hire and a great early contribution.
Q: Should I read the whole thing eventually? No. You'll deeply learn the parts you work in and keep a rough map of the rest, forever. That's how everyone operates, including the staff engineers. Comprehensive reading is a poor use of time compared to task-driven exploration.
Q: How do I not annoy my team with questions? Batch them in a log, ask "where" instead of "what," and try to answer each yourself first. A thoughtful batched question once a day is welcome; a stream of un-attempted ones is draining. Show your work and people are glad to help.
Q: What if I'm too scared to ship in week one? Pick something genuinely tiny — a typo, a label, a doc fix. The risk is near zero and the workflow lesson is enormous. Shipping small early also breaks the fear, which only grows the longer you wait to push your first change.
Q: Can AI tools speed up onboarding? A lot, actually. Asking an AI assistant to explain an unfamiliar file, summarize a module, or trace where a function is used turns hours of reading into minutes of orientation. Treat it as a tireless tour guide for the neighborhood you're standing in.
I used to think onboarding meant understanding the codebase. It doesn't, and trying to is how you waste your first month feeling stupid.
Don't read the codebase. Run it, trace one path through it, and ship one small thing. Orientation beats comprehension, and doing beats reading.
A week is enough to go from lost to landing a real change — not because you've understood the system, but because you've learned how to find your way inside it and how the team actually ships. The rest fills in naturally, one task at a time.
If you're onboarding somewhere new this month, try the run-it-then-trace-it order instead of cover-to-cover reading — and the senior-developer pillar collects more playbooks like this one.
So if you're staring down a giant unfamiliar codebase: stop trying to read it. What's the smallest thing you could ship by Friday?
I spent years saving the hardest task for when I 'felt ready.' Doing it first instead quietly fixed my focus, my dread, and my output.
I tracked every distraction for a week and was horrified by what I found. Then I fixed the three that mattered most.
No following, no network, no luck. Just an unglamorous system I ran for eighteen months. Here's exactly what I did.
Comments
Sign in to join the conversation
No comments yet. Be the first to share your thoughts!