Orient

Arriving in a codebase, the temptation is to start reading files. Files are the least informative thing available.

The goal is not coverage. It is a model good enough to predict: where would a change of this kind go, what would it touch, and what would object.

What the system is for

Before structure, purpose. A system's shape only makes sense against what it is trying to do — the same directory layout is elegant for one purpose and absurd for another.

The README if it is honest, and what runs when the thing starts. Follow one real path from entry point to outcome — one request, one command, one frame. A single traced path teaches more than any amount of breadth, because it shows what the system actually does as opposed to what it contains.

Find where decisions live

Most of a codebase is consequence. A small part is decision, and that part is what needs to be understood.

Look for: