I get asked to look at unfamiliar codebases a few times a quarter. Sometimes for consulting, sometimes for a friend, sometimes because someone wants a sanity check before an acquisition. I've gotten quick at it. Here's roughly how I do it.
The first hour
- Read the top-level README. Note what it claims. Note what it omits.
- Open `package.json` (or equivalent). Read every dependency. Three you don't recognize: those are the team's bets.
- `git log --oneline | head -200`. Look for streaks, gaps, and the names that show up most. Gaps are interesting.
- Find the longest file. Read it. It's almost always the heart.
The second hour
Now I follow one user-visible feature from URL to database. Whatever shape that is: route, controller, service, ORM, migration, table. The path itself tells you the team's worldview. Are there layers, or just functions? Are tests woven through, or piled at the end? Where does the codebase get nervous?
The third hour
- Skim the test directory's directory structure, not the tests themselves. The shape tells you what they trust.
- Read the most recent ten PRs that have any reviewer comments. The arguments are the architecture.
- Find the oldest comment in the codebase. Read the file around it.
By hour four I can usually tell you the three things keeping the team up at night, even if nobody on the team has said them out loud yet. The codebase always tells. You just have to read it like a person, not like a compiler.