Every developer eventually faces the same wall: a repository someone else built — a new job's monolith, an inherited side project, an open-source tool you need to modify — and the temptation is always the same. Open the first file, start reading line by line, drown by page three. Codebases aren't meant to be read like books; they're systems meant to be poked. The developers who onboard fastest aren't faster readers — they run better experiments. Here's the method.
Run it before you read it#
A codebase you can execute is infinitely more legible than one you can't. Before opening a single source file:
- Get it building. Follow the README even where it seems obvious; the friction points you hit are themselves information about the project's maturity.
- Start it locally and click through every flow you can find as a user.
- Change something trivially visible — a label, a color — and confirm you can see the change. This proves your edit-run loop works, which converts all later reading from theory into verification.
Half the confusion newcomers feel about unfamiliar code is actually uncertainty about whether their mental model connects to behavior at all. Running it dissolves that first barrier.
Follow the data, not the files#
Files are organized by architecture fashion; data flow is organized by reality. Instead of reading directory by directory, pick one concrete question — "what happens when a user submits this form?" — and trace the answer end to end: the event handler, the API call it makes, the route that receives it, the database rows it touches, the response shape coming back.
One traced request teaches you more than an afternoon of file browsing, because you encounter only load-bearing code — everything involved in a real user action matters, everything else can wait. Repeat for two or three core flows and the system's skeleton emerges on its own. A whiteboard sketch of boxes and arrows per flow feels childish and works anyway; the diagrams you draw yourself encode understanding no generated diagram can.
Tests are documentation that can't lie#
Comments rot; specs drift; but a passing test suite describes what the code currently actually does, enforced on every commit. In an unfamiliar repo:
- Read test names first. They're a behavioral table of contents —
rejects expired sessions,retries failed webhooks twice— telling you the system's contract in plain language. - Read one test body per feature area, setup through assertion. Tests demonstrate intended usage of internal APIs better than any docs page.
- Find the test for the thing you're changing before changing it. It tells you which behaviors neighbors depend on.
And when there are no tests? Writing your first one for the area you're exploring forces exactly the questions that build understanding — how does this get constructed, what are its inputs, what should happen at the edges?
Make throwaway changes#
Reading answers "what does this say?" — experimentation answers "what happens if?", which is usually the real question. In a scratch branch, safely:
- Delete a suspicious-looking block and run the tests. Failures map dependencies faster than any import search.
- Add a log line in the middle of a mystery function and trigger the flow. Runtime truth beats static guessing about order and values.
- Rename a variable you don't understand to
TODO_UNDERSTAND_MEand see everywhere it surfaces.
None of this ships. Its entire value is the feedback loop: hypothesis, poke, observe. Senior engineers look psychic in unfamiliar code largely because they run five cheap experiments while everyone else is still scrolling politely through files.
Git history is senior-engineer whispering#
git log --oneline gives you the plot summary; git blame -L on a confusing block tells you which change introduced it and why (read the commit message, then the PR if referenced). A line that looks pointless almost always had a reason — a bug fixed, a workaround added — and history hands you that context without a meeting. Conversely, huge commits labeled "misc fixes" tell you where the bodies are buried. Ten minutes of archaeology routinely replaces an hour of speculation.
Asking is not cheating — but batch it#
If humans who know the codebase exist, use them efficiently: collect questions as they arise, attempt each briefly yourself first, then bring the survivors in one focused session rather than a drip of interruptions. "I traced X through Y and got stuck at Z" earns detailed help; "how does this work?" earns a sigh.
The compounding part#
Somewhere around the third unfamiliar codebase, the process itself becomes the skill: spin up, trace a flow, skim its tests, poke, sketch, ship a small change. What felt like drowning the first time becomes routine reconnaissance — and that skill, unlike any particular framework, transfers to literally every job and project you'll ever touch.
Related: deep work sessions pair well with exploration blocks, and writing workflow systems applies the same batching logic to documentation.
