How to Onboard Into a New Codebase Without Drowning

TL;DR - A new codebase is disorienting by default. The goal of week one is orientation, not contribution. - Read the README and setup docs first. Get the app running locally before you touch anything. - Trace one feature end-to-end to understand data flow and architecture. Don't try to understand everything at once. - Read recent merged PRs to understand how this team writes code and what their review process looks like. - Find the tests. They document intended behavior better than most comments. - Build your mental map over four weeks, not four days. The engineers who onboard well are the ones who go slow at the start.

Your first week at a new job, the codebase you're looking at is probably larger, older, and messier than anything you've ever built yourself. Files you don't recognize. Abstractions with names that make no sense. Patterns that seem inconsistent. A folder structure that apparently made sense to someone.

This is normal. Every engineer goes through it.

The engineers who handle it well aren't the ones who understand everything fastest. They're the ones with a systematic approach. They know what to look at first, what to ignore for now, and how to build a mental map incrementally over days and weeks.

Here's that approach.

Week One, Day One: Before You Write Anything

The most common mistake new engineers make is trying to write code before they understand what they're writing into. It's tempting, especially when you want to show you're productive. Resist it.

The goal of the first several days is orientation, not contribution. Understanding the codebase is the work. You are not behind if you haven't shipped anything by the end of week one. Most experienced engineers will tell you the worst onboarding disasters they've witnessed came from someone moving fast too early.

Step 1: Read the README and Setup Docs First

Start here, every time, no matter how impatient you are.

The README tells you what the project is, how to set it up, and often the high-level architecture or entry points. Even if it's outdated (most are at least slightly outdated), it gives you a starting point and a vocabulary.

Pay attention to: - What the project actually does (not just technically, but what problem it solves) - Dependencies and setup requirements - How to run the tests - Any architecture overview or "how this is organized" sections - Links to wikis, design docs, or runbooks

If there's a wiki or internal documentation, read the most recently updated sections. They're usually the most accurate.

Ask your manager or onboarding buddy: "Is there documentation I should read before digging into the code?" Most engineers are happy to hand you a reading list. It saves them from having to explain things from scratch.

Step 2: Get the App Running Locally

Before you look at a single line of code with any purpose, get the application running on your machine.

This might take a while. Local development environments are notoriously finicky, especially if the setup docs are out of date. Note everything you have to do that isn't in the documentation. When you get it working, either update the docs or at minimum write down what you did, because you'll likely need to help the next person who joins.

Running the app locally gives you something essential: a way to verify your understanding. As you start tracing code, you can actually run things, watch what happens, add log statements, and test behavior. Without a running local environment, you're reading code in the abstract.

Once it's running, do the same things a user would do. Click through the app. Submit forms. Trigger the main flows. You're building intuition about what the system does before you start understanding how it does it.

Step 3: Trace One Feature End-to-End

This is the most effective onboarding technique most people don't use.

Pick one small, well-defined feature. A form submission. A search. A login. A data export. Something with a clear start (user does X) and a clear end (system returns Y).

Then trace it through the codebase.

In a web app, this usually means:

Find where the route is defined
Find the controller or handler that receives the request
Find the service or model that does the actual work
Find how data gets read from or written to the database
Find how the response is built and returned

At each step, note what you find. You don't need to understand every line. You're building a map, not a textbook. The question is: "what does this thing call next?"

As you trace, you'll notice patterns. Maybe all the business logic lives in service objects. Maybe the data access layer is abstracted behind a repository pattern. Maybe everything is in the controllers (a common sign of an older Rails app). You're not judging these choices yet. You're learning the conventions.

Do this for two or three different features and you'll start to see the shape of the architecture. After five, you'll feel significantly more oriented.

Step 4: Read Recent Merged PRs

Before you write code that belongs in this codebase, understand how this team writes code.

Go to the pull request history on GitHub (or whatever version control system the team uses) and read the last 15-20 merged PRs. Pay attention to:

Style and conventions. How are variables and functions named? How long are functions? What do the commit messages look like? How much documentation do they write? The answers to these questions are the implicit style guide that wasn't written down anywhere.

How reviews happen. What do reviewers comment on? What gets approved without discussion? What gets pushed back? This tells you what the team cares about and what will get flagged in your first PRs.

The scope of individual changes. Are PRs usually small (one focused change) or large (many files changed at once)? Understanding the expected PR size helps you scope your own contributions correctly.

What kinds of things get built. Even a few weeks of PR history gives you a sense of what kinds of problems the team is solving and how they approach them.

This is not the same as reading the codebase. PRs show you how the code changes over time, which is different from and often more revealing than the current state.

Step 5: Find the Tests

Tests are the most honest documentation in most codebases.

Comments get stale. Documentation gets out of date. READMEs get neglected. But tests (when they're maintained) describe what the system is supposed to do in a way that's directly tied to the current code.

Find where the tests live. In most frameworks, there's a conventional location: a /test or /spec directory, mirroring the structure of the application code.

Read through the tests for the feature you traced in Step 3. The tests will show you: - What inputs the code is supposed to handle - What the expected outputs are - What edge cases the team thought about - What the code is explicitly not supposed to do

If you run the tests and something fails, note it. Don't fix it yet (that's a rabbit hole to fall into too early), but a test failure is useful information about the current state of the codebase.

Running the full test suite gives you something else: a baseline. You'll know whether your changes broke something. Any time you make a change, running the tests is the fastest way to check if you accidentally broke something you didn't touch.

What Not to Do

Don't dive into the biggest file. The largest file in a codebase is usually the oldest, the most complicated, and the most central to how the system works. It's also the worst place to start. You'll get lost and it won't help you build orientation.

Don't try to understand everything before you do anything. A codebase is too large to understand completely before starting. The goal is a working mental model, not total comprehension. You'll fill in the gaps as you go.

Don't ask questions before trying yourself. Every question you ask a senior engineer costs them focus. Spend twenty to thirty minutes trying to figure something out before you ask. If you're still stuck, ask, but lead with what you tried: "I looked at X and Y, and I'm confused about Z." This is the correct format. It shows you tried, and it helps them give you a more useful answer.

Don't make big changes early. Your first few contributions should be small and well-understood. A bug fix with a clear description. A test that wasn't written. A documentation improvement. These changes let you practice the team's workflow without the risk of breaking something significant before you understand the system.

For more on how to ask questions that don't annoy your team, see the companion guide on asking questions at work as a junior developer.

Building Your Mental Map Over Weeks 1-4

You can't build full familiarity with a codebase in a week. The goal for week one is orientation. Here's a rough arc:

Week 1: Get set up. Get the app running locally. Trace a few features. Read the recent PRs. Don't write significant code.

Week 2: Make your first small contribution. A bug fix or a simple test. Go through the full PR process: branch, change, PR, review, merge. Learn how the team deploys. Start identifying areas of the codebase you want to understand better.

Week 3: Take on something slightly more substantial. Read more of the codebase adjacent to what you're working on. Start to understand how different parts connect. Ask your manager or senior engineer for a code tour of a module you don't understand yet.

Week 4: You should start to feel less lost. Not comfortable, but less lost. You know how to navigate. You know where things live. You know what the tests look like. You know how PRs work on this team. This is the baseline.

Full familiarity with a large codebase takes months. That's normal and expected. Your first 90 days at a job are a learning process, and the best engineers embrace that rather than pretending to know more than they do.

For a broader look at how to approach the first three months at a new job, see the first 90 days guide.

How to Get Help Without Being a Burden

At some point in every onboarding, you need help. The goal is to ask in ways that respect your colleagues' time and demonstrate that you're doing your part.

The general rule: try before asking, and when you ask, show your work.

"I'm trying to understand how the authentication middleware works. I read through the middleware module and traced it back to the request handling in the router, but I'm confused about how the session store is being used here. Do you have a few minutes to walk me through it?" is a good question.

"I'm confused about the authentication" is not.

The first question tells your colleague exactly what you looked at, where you're stuck, and what specific clarification you need. It takes them thirty seconds to orient and give you a useful answer. The second requires them to figure out what you already know before they can help.

If you're working with a senior engineer on your team, building that relationship thoughtfully over your first weeks matters. See the guide on working with a senior engineer for how to approach that dynamic.

The Bigger Picture

The onboarding experience is a preview of what the job will always involve: you don't know something, you have to figure it out, you do it systematically and without panicking.

Junior engineers who onboard well tend to have one thing in common: they go slow at the start. They read before they write. They ask good questions. They don't try to prove themselves through volume of output in the first two weeks.

The engineers who struggle are often the ones who started writing code before they understood what they were writing into. They move fast, they break things they didn't know were connected, and they spend more time on cleanup than the engineers who went slow and understood things first.

Your job in the first few weeks is to learn the codebase. That is the work. Everything else is slower and harder if you skip it.

If you want help preparing for your first role and building the habits that make onboarding easier, here's how the Globally Scoped program works.