Your First Week on a New Codebase: A Day-by-Day Checklist

The first week on a new codebase sets the tone for months. Engineers who spend it waiting for access, reading random files and hesitating to ask questions often still feel lost in week four. Engineers who follow a deliberate plan, with a running build on day one, a traced flow by day three and a small merged change by day five, tend to feel useful by the end of the week and confident by the end of the month.

This is a day-by-day checklist for that week. It is written for the new engineer, but it works just as well for a manager or onboarding buddy planning someone's first days. Adapt the specifics to your stack and team. For the team-side view of onboarding, including what to prepare before someone starts, see onboarding developers to a large codebase.

Key takeaways

• Day 1 goal: everything runs locally, and you know who to ask. Nothing else matters as much.
• Day 2: build an inventory of the system from structure and history, before reading much source.
• Day 3: trace one or two critical flows end to end, with a debugger.
• Day 4: pick up a small, real ticket and get it into review.
• Day 5: merge it, write down what you learned, and get your map corrected by someone senior.
• Keep a running "questions and surprises" log all week. It becomes your best onboarding artifact and a gift to the next new hire.

Before day one (if you can)

If you have any contact with the team before starting, ask for these. If not, make them your first requests on day one.

[ ] Repository access (and any related repos: infra, shared libraries, docs)
[ ] Accounts: CI, error tracking, logs/metrics, issue tracker, chat, cloud console (read-only is fine)
[ ] Local setup doc or README section, even if outdated
[ ] Name of an onboarding buddy
[ ] One sentence on what the team is working on this quarter

Day 1: Get it running and meet people

The single most important outcome of day one is a working local environment. Every later step depends on being able to run code, tests and the app.

[ ] Clone the repo(s) and follow the setup instructions exactly as written
[ ] Note every step that is wrong, missing or confusing (you will fix the doc later)
[ ] Install the right toolchain versions (.nvmrc, .tool-versions, go.mod, rust-toolchain.toml, .python-version)
[ ] Start dependencies (docker compose up, local database, seed data)
[ ] Run the full test suite once, and record how long it takes and what fails
[ ] Start the app and perform the main user action by hand
[ ] Run the linter and formatter, and set up your editor to match (format on save, same config)
[ ] Make a trivial local change and see it reflected (hot reload, rebuild)
[ ] Meet your buddy; agree on a daily 15-minute check-in for the week
[ ] Join team channels; read the last two weeks of the main one

Useful commands for figuring out what to install:

# Version files that pin toolchains
ls -a | rg "nvmrc|tool-versions|python-version|ruby-version|rust-toolchain|go\.mod"

# What the project expects you to run
jq .scripts package.json        # Node
make help 2>/dev/null || rg "^[a-zA-Z_-]+:" Makefile

If setup takes more than a day, that is a finding, not a personal failure. Write down exactly where it broke. A setup doc fixed by the newest person is the most valuable doc change a team gets.

Start your log today. A simple file works:

# Onboarding log

## Questions
- Why are there two user tables (users, accounts)?

## Surprises
- Tests need Redis running even for unit tests

## Setup issues
- README says Node 18; .nvmrc says 20

Day 2: Map the system from the outside in

Today you build an inventory: what the system is made of and how it fits together. Read structure and history before reading much source.

[ ] Read the README, any docs/ folder, and architecture notes; mark what seems outdated
[ ] List every deployable process (web, API, workers, schedulers) from Dockerfiles, compose, CI deploy jobs
[ ] List the top-level folders or packages with a one-line guess at each one's purpose
[ ] Read the dependency manifest; note the framework, ORM, queue, cache and test runner
[ ] Look at the database schema or latest migrations; list the five most important tables
[ ] Run git history commands to find the hottest files and the most active contributors
[ ] Get the full list of HTTP routes (framework command or search)
[ ] Draw a rough box-and-arrow sketch: processes, data stores, external services

# Hottest files in the last 6 months
git log --since='6 months ago' --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20

# Who has been active
git shortlog -sn --since='6 months ago' | head -10

The hottest files tell you where the important logic is and where you will probably work. The active contributors tell you who to ask about what. For more on finding where things start, see finding the entry point of any repository.

Day 3: Trace critical flows

Today you go deep on one or two things the business depends on. Ask your buddy: "What are the two most important user actions in this product?"

[ ] Pick flow 1 (for example: sign in, or the main create action)
[ ] Capture a real request from the browser network tab or logs
[ ] Follow it from route through middleware, handler, service, data layer and back
[ ] Set breakpoints and step through it locally
[ ] Turn on query logging; see the actual SQL
[ ] Find any async work it triggers (jobs, events) and where it is consumed
[ ] Write a short trace with file:line at each step
[ ] Repeat for flow 2 if time allows
[ ] Read the tests for those flows

The method for a single flow is covered step by step in tracing a request through a web app. By the end of today you should be able to explain both flows to someone else without opening the code.

Day 4: Take a small real ticket

Reading only takes you so far. Today you change something. Ask your buddy or lead for a ticket that is:

• Small: a few hours of work, ideally a few dozen lines.
• Real: it ships to users or fixes a real bug, not a make-work exercise.
• Contained: one area of the code, ideally near a flow you traced.
• Reviewable by someone available this week.

Good first tickets are small bug fixes with a clear reproduction, an improvement to an error message, a missing validation, a test for an untested path, or the setup doc fixes from day one.

[ ] Reproduce the bug or confirm the current behavior locally
[ ] Find the relevant code, and check who else calls it before changing it
[ ] Write or update a test first if the area has tests
[ ] Make the change; keep the diff small
[ ] Run the relevant tests, linter and type checker locally
[ ] Read the team's PR template and contribution guidelines
[ ] Open the PR with a clear description: what, why, how tested
[ ] Ask a specific reviewer, and say it is your first PR so they can point out conventions

Checking who calls a function before you change it is a habit worth building from the first ticket. Even in a small change, a shared helper might be used in places you have not seen yet.

Day 5: Merge, reflect and get corrected

[ ] Address review feedback; ask about any comment you do not understand
[ ] Get the PR merged and, if possible, watch it deploy
[ ] Turn your day 2 sketch and day 3 traces into a one-page map
[ ] Book 30 minutes with a senior engineer to review the map; take notes on corrections
[ ] Go through your questions log with your buddy; mark which are answered
[ ] Submit a PR fixing the setup doc with everything you hit on day one
[ ] Write down three areas you want to learn next, and share them with your lead

The map review is the highest-leverage meeting of the week. Arrive with a concrete draft, not "can you explain the architecture?" Senior engineers can correct a wrong arrow in seconds and will usually add history that is written down nowhere else.

Habits to keep after week one

• Read merged PRs in your team's area for ten minutes a day.
• Keep the log going. Surprises are signals of missing docs or real design problems.
• Ask early. A rule of thumb many teams use: if you have been stuck for 30 to 60 minutes and tried the obvious things, ask. Say what you tried. The guide to asking better questions about code covers how to phrase it so you get a quick answer.
• Update the map each time a flow surprises you.

For managers and buddies: preparing the week

If you are on the other side, a few things make the checklist above work:

Prepare	Why
Access granted before day one	Waiting for permissions wastes the most motivated days
A tested setup doc	If it is broken, the new person learns the team does not maintain docs
Two critical flows named	Saves them guessing which parts matter
Two or three candidate first tickets	Small, real, contained, with a reviewer available
A daily 15-minute check-in	Low-cost way to unblock and answer questions
A senior engineer's time on day five	Correcting the map is where the deepest learning happens

Tools that help in week one

Days two and three are where a new engineer spends the most time building context from scratch. A guided walkthrough gives them a draft to check rather than a blank page. OpenVisio's Tour indexes a GitHub repo in the browser and walks through the codebase stop by stop, with article, code, diagram and slide views, which pairs well with the day two inventory. For specific questions during day three and four, such as "where is the session checked for API routes?", Ask gives an answer with the relevant code in view.

Whatever tools you use, the shape of a good first week stays the same: running code on day one, a map by day two, traced flows by day three, a real change by day four, and a corrected model by day five.