Onboarding to a New Project: A Developer's Checklist

The first two weeks on a new project shape the rest. Get the right questions answered early and you ramp faster, miss less context, and avoid the awkward "actually, why is this set up this way?" three months in. This is the checklist I run through.

Setup, end-to-end

• Clone the repo and get the app running locally on day one. Whatever issues come up, they are part of onboarding — do not skip.
• Run the test suite. If any fail on a fresh clone, that is signal — flag it and ask.
• Deploy a trivial change to staging. The deploy pipeline is part of the codebase you need to understand.

Read the central files

Find the main router, the main models, the main API entry points. Read them. Do not try to understand every file — try to map the spine. Once you know where the bones are, the muscles make sense.

Ask why, not just what

When something looks unusual, ask the person who would know. "I see you are using X for Y — was that a deliberate choice over Z?" gets you the constraint that drove the decision. The answer might change the way you think about half the codebase.

Document as you go

Keep a notes doc with the things you learn. Where things are, who owns what, surprises in the codebase. Share it with the team — they often discover docs gaps from your notes that they had stopped noticing.

Ship something small in week one

Even a tiny change — a copy fix, a typo, a small refactor — proves you can navigate the full pipeline (clone → change → review → deploy). Get that loop closed early. It builds confidence and surfaces process issues fast.