Reading a codebase you did not write
· 1 min read
Most teams treat an unfamiliar codebase like a directory tree. That is useful eventually, but it is the wrong first shape. A codebase is a running argument about product constraints, historical tradeoffs, and the fastest path that still worked.
Before making changes, build a small map: where requests enter, where state changes, where failures surface, and which files seem to carry policy. The goal is not to know everything. The goal is to make the next question cheaper.
Reading notes
- Start with entry points, not folders.
- Trace one successful path end to end.
- Name the seams before changing them.
- Record questions beside the code.