I've joined four companies, inherited three legacy systems, and consulted on dozens of codebases ranging from 50K lines to over 2 million. Every single time, the advice I got was the same: "Just read the code." That advice is garbage.
Reading code without a system is like reading a dictionary to learn a language. You'll recognize words but never understand sentences. After years of doing this wrong, I built a repeatable method that cuts codebase comprehension time from months to days.
A 2018 field study by Xin Xia and colleagues observed 78 professional developers across seven projects and found that about 58% of recorded time went to program comprehension activities. The result describes that study’s setting rather than every developer’s working day. Yet nobody teaches this skill. Computer science programs focus on writing code. Bootcamps focus on building projects. Books focus on algorithms and patterns.[1]
Understanding an existing codebase is a fundamentally different skill than writing new code. When you write code, you control the architecture, the naming, the abstractions. When you read someone else's code, you're reverse-engineering decisions made by people you've never met, under constraints you don't know about.
I was wrong about something for years. I thought the key to understanding a codebase was reading more code. It's not. The key is reading the right code in the right order.
Figure 1. Build system context before investigating a particular implementation.
Here's the framework I use. I call it the Codebase Comprehension Matrix. It breaks understanding into four layers, each with specific questions to answer and artifacts to produce.
Layer
Goal
Key Questions
Time
L1: Boundaries
Know what the system does
What are the inputs/outputs? Who uses this? What does it depend on?
2-4 hours
L2: Highways
Know how data flows
What are the main request paths? Where does data enter and leave?
1-2 days
L3: Neighborhoods
Know how modules work
What does each module own? How do modules communicate?
3-5 days
L4: Houses
Know implementation details
Why was this specific approach chosen? What are the edge cases?
Ongoing
Most developers jump straight to L4. They open a random file, start reading, get confused, open another file, get more confused, and eventually just ask someone. This is backwards. You need context before details.
Your first job is not to read code. It's to understand the system from the outside.
Step 1: Read the deployment configuration.
Open the Dockerfile, docker-compose.yml, Kubernetes manifests, or whatever deployment config exists. This tells you what the system actually is. Is it a single service or twenty? What databases does it connect to? What external services does it call?
package.json, go.mod, Cargo.toml, requirements.txt. Don't read every dependency. Look for categories: what web framework, what ORM, what message queue, what auth library. This gives you the technology stack in 10 minutes.
Step 3: Map the external boundaries.
Draw a simple box diagram. Your system in the middle. Everything it talks to on the outside: databases, APIs, message queues, file systems. Label each connection with the protocol (HTTP, gRPC, SQL, AMQP). This single diagram will be your anchor for everything else.[2]
Step 4: Find the entry points.
Every system has entry points: where external requests come in. For a web app, it's the router. For a CLI tool, it's the main function. For a message consumer, it's the handler registration.
bash
# For a Node.js/Express appgrep -r "app.get\|app.post\|router.get\|router.post" --include="*.ts" -l# For a Next.js appfind app src/app -type f \( -name 'page.tsx' -o -name 'route.ts' \) -print 2>/dev/null
At the end of Layer 1, you should be able to explain to a non-technical person what the system does, what it connects to, and where requests come from. If you can't, you're not ready for Layer 2.
Figure 2. Follow a user action through decisions, data and side effects.
Now you trace the most important paths through the system. I call these highways because they carry the most traffic.
Step 1: Identify the top 3-5 user actions.
Ask the team: "What are the most common things users do?" For an e-commerce app, it's browse products, add to cart, and checkout. For a SaaS dashboard, it's login, view data, and create reports.
Step 2: Trace each action end-to-end.
Start at the entry point you found in Layer 1. Follow the code path from the HTTP handler through the business logic to the database query and back. Don't read every line. Skim function signatures, read the interesting parts, and skip the obvious parts.
I use a specific notation for this:
POST /api/orders
-> OrderController.create()
-> OrderService.createOrder()
-> validates input (Zod schema)
-> checks inventory (InventoryService.check())
-> creates order record (prisma.order.create())
-> publishes event (EventBus.publish("order.created"))
<- returns { orderId, status }
<- 201 Created
This text-based trace is worth more than reading 50 files. You see the actual flow, the key decision points, and the side effects.
Step 3: Find the data model.
Open the database schema. In a Prisma project, that's schema.prisma. In a Rails project, that's db/schema.rb. Read every table and its relationships. The data model is the closest thing to ground truth in any system because the code can lie but the database schema rarely does.
Step 4: Identify the patterns.
By now you've read enough code to notice patterns. Does this codebase use a service layer? Repository pattern? Event-driven architecture? Are there consistent naming conventions? Document what you see because these patterns are the grammar of this particular codebase.
This is where things get interesting. Which modules call which? Are there circular dependencies? Is the dependency direction clean (UI -> Business Logic -> Data) or messy?
Tests record behaviours the team intends to protect. Check whether they run and what their assertions actually cover. Read the test file names first. They tell you what behaviors the team considers important. Then read individual tests for the modules you care about most.
This is where you read specific implementations. But now you have context. You know what the system does (L1), how data flows (L2), and what each module owns (L3). Reading specific code is 10x faster with this context.
When to go to Layer 4:
When you need to fix a bug in a specific module
When you need to add a feature that touches specific code
When you're reviewing a PR and need to understand the surrounding code
How to read a specific file effectively:
Read the imports first. They tell you what this file depends on.
Read the exports. They tell you what this file provides.
Read the public interface (function signatures, class methods). Skip the implementations.
Now read the implementation of the specific function you care about.
Here's where I disagree with most advice: you should not read code the way you read a book, top to bottom. Code is a graph, not a narrative. It has nodes (functions, classes, modules) and edges (calls, imports, data flow).
Read it like a graph. Start at a node that matters. Follow the edges that are relevant. Ignore the rest. I've seen developers spend three days reading a 10,000-line file top to bottom and retaining almost nothing. I've seen other developers understand a 500,000-line codebase in a week by following the right paths.
I've tried dozens of tools for codebase understanding. Here's what actually works:[4][5][6]
Your IDE's "Go to Definition" and "Find All References." These two commands are worth more than any visualization tool. Use them relentlessly.
git log with path filtering.git log --oneline --follow path/to/file.ts tells you the history of a file. git log --oneline --since="6 months ago" -- src/orders/ tells you what's been actively developed.
grep and ripgrep.Full-text search is underrated. When you see a function called and want to know where it's defined, rg "function processOrder" is faster than any IDE index for large codebases.
Dependency analysis tools.madge for JavaScript/TypeScript, go mod graph for Go, cargo tree for Rust. These show you the actual dependency graph, not what you imagine it to be.
AI-powered code understanding tools. Tools like Sourcegraph Cody, GitHub Copilot Chat, and Cursor can answer questions about your codebase. They're not perfect, but they're useful for getting a quick explanation of a confusing function. Don't trust them blindly though. Verify their answers against the actual code.
Mistake 1: Trying to understand everything before doing anything. You don't need to understand the entire codebase to fix a bug or add a feature. Use the Comprehension Matrix to get to Layer 2 quickly, then go to Layer 4 only for the specific area you're working in.
Mistake 2: Not drawing diagrams. Working memory is limited, and a codebase contains many interacting concepts. A codebase has thousands of concepts. Offload to paper. Even ugly hand-drawn diagrams are better than trying to hold it all in your head.
Mistake 3: Not asking questions. If the team has a Slack channel, use it. "Why does OrderService call AuthService.refreshToken()?" is a perfectly good question. The answer might be "historical accident, we should fix that" or "there's a good reason, let me explain." Both answers save you hours.
Mistake 4: Ignoring the tests. Tests encode institutional knowledge about edge cases, expected behavior, and past bugs. A test named it("handles the case where user has both legacy and new permissions") tells you something important about the system's history.
Mistake 5: Reading code without running it. Set up the development environment on day one. Run the app. Click through the UI. Hit the API with curl. Seeing the system running makes the code 10x more understandable because you can connect code paths to observable behavior.
Here's my concrete playbook for the first two weeks at a new codebase:
Day 1: Layer 1. Deployment configs, dependency manifests, boundary diagram, entry points. End the day with a 5-minute presentation to yourself explaining what the system does.
Days 2-3: Layer 2. Trace the top 5 user actions. Read the database schema. Document the patterns you see.
Days 4-7: Layer 3 for the modules most relevant to your team's work. Map boundaries, dependencies, and read key tests.
Week 2:Start contributing. Pick a small bug or feature. Use Layer 4 to understand the specific code you need to change. Your PR will probably get feedback about conventions you missed. That's fine. That's learning.
Ongoing: Update your mental model as you learn more. The Comprehension Matrix isn't one-and-done. You'll revisit layers as you discover new things.
This isn't the only way to understand a codebase. But it's a system, and having a system beats wandering randomly through files every time. I've used it on a 2.1 million line Java monolith, a 400-service microservices architecture, and a 30K line Next.js app. It works at every scale because it prioritizes the right information at the right time.
Stop reading code like a book. Start reading it like a map.
What should I read first in an unfamiliar codebase?
Start with deployment files, dependency manifests and entry points to learn what runs and what it connects to. Then trace one important user action through the code and database before opening unrelated implementation files.
Do I need to understand the whole repository before contributing?
Build enough context to identify the relevant flow, its dependencies and the behaviour the change must preserve. The post recommends starting with a small contribution and deepening that understanding through review.
What should a useful codebase map contain?
Record system boundaries, important request or event paths, module responsibilities and the dependencies between them. Add the relevant data stores and external services so the map helps answer a concrete change question.
Can an AI assistant explain the repository for me?
It can help locate code and explain unfamiliar functions, especially when it has repository context. Follow its references, inspect related tests and check the running behaviour before relying on the explanation for a change.
Your PR data reveals team bottlenecks invisible in standups. Here's how to measure TTFR, review distribution, and cycle time with the REVIEW framework.
No single person can hold a large codebase in their head. A knowledge graph externalizes understanding into a queryable structure. Here's the 4-week playbook to build one.
Choose code search tools for text, symbols and cross-repository exploration. Use ripgrep, GitHub and Sourcegraph queries to find code and related changes.
Apply developer documentation best practices with ADRs, comments and tested examples. Use the WRITE system to keep changes reviewable and find stale guidance.