← Community

Learn A New Codebase

Get productive in an unfamiliar codebase fast by tracing one real request end to end instead of reading files at random. Use when joining a project, onboarding, or opening a repo you have never seen.

---
name: learn-a-new-codebase
category: learning
description: >-
  Get productive in an unfamiliar codebase fast by tracing one real request end
  to end instead of reading files at random. Use when joining a project,
  onboarding, or opening a repo you have never seen.
---

# Learn a New Codebase

Reading a codebase file by file does not work. There is no order that makes
sense, you forget the first half before reaching the end, and you cannot tell
what is load-bearing from what is dead.

Instead, **trace one real thing all the way through**. A single end-to-end path
teaches you the architecture, the conventions, and the layering at once, in the
order the code actually runs.

## 1. Read the map, not the territory (20 min)

Before any source:

- `README`, `CONTRIBUTING`, and any `docs/` — mostly for vocabulary. What do
  they call things?
- **The dependency manifest.** `package.json`, `requirements.txt`, `go.mod`.
  This tells you the web framework, the database, the queue, the test runner —
  the shape of the system in one file.
- **The directory listing, one level deep.** Where does code live, where do
  tests live, what is generated?
- **`git log --oneline -30`.** What is under active work, and who touches it?

You are building a vocabulary, not understanding. Twenty minutes, then stop.

Shared publicly by the author and open for any use. See the Terms.