Module 12 · Lesson 02
Reading Unfamiliar Codebases with Claude
Reading time: 18 minutes Track: Claude Fluency for Teams · Developer path
The orientation problem
Every developer knows the pain of arriving at an unfamiliar codebase. The questions are the same every time: What does this actually do? Where is the entry point? How does authentication work? Where does this data come from and where does it go? Who wrote this and why did they make this decision?
Answering these questions traditionally requires reading documentation that may be outdated, asking the original developers who may not be available, and running the code while reading it — a process that takes days to get to working proficiency.
Claude Code can compress that orientation from days to hours. Here's the workflow.
The three-layer orientation
Layer 1: Architecture overview (5-10 minutes)
Start with the big picture before any specifics.
Give me an architectural overview of this codebase. Cover:
- What it does and who uses it
- The main components/services and how they relate to each other
- The data flow for a typical user request
- Any non-standard patterns or architectural decisions I should know about
- The testing approach
Read Claude's response carefully. Push back or ask follow-ups wherever the description doesn't match what you see.
Layer 2: Data model and key abstractions (10-15 minutes)
Understanding the data model unlocks everything else.
Walk me through the core data model. What are the main entities, what do they represent,
and what are the important relationships between them?
Also identify the key abstractions or interfaces that the rest of the codebase depends on.
Layer 3: Specific flows and components (15-20 minutes)
Once you have the overview, drill into the areas relevant to your work.
Trace the complete flow for [specific user action or API call]:
- From entry point to response
- Every significant function or class involved
- Any side effects (database writes, events, external calls)
- The happy path and the main error cases
High-value orientation prompts
Understanding a specific file:
Read [file path]. Tell me: what is this module responsible for,
what does each public function do, what does it depend on,
and what depends on it?
Understanding a decision:
Why is [X pattern/technology/approach] used here instead of the more standard [Y]?
Look at the code and git history for clues.
Finding your entry point:
I need to add [feature description]. Where in the codebase would I make this change?
What files would I need to read first, and what would I need to create or modify?
Understanding test coverage:
What's the test coverage like for [specific component]?
What scenarios are covered and what significant cases are missing?
Validating Claude's understanding
Claude Code is reading files and generating descriptions — it can misread or mischaracterize complex code. Build in verification:
- After Claude describes a flow, trace one path yourself in the actual code
- Ask Claude "what's the one thing I most likely misunderstood from your overview?" — this surfaces caveats Claude has but didn't volunteer
- For critical architectural claims, check the relevant files directly
The "what not to do" question
One of the most valuable orientation questions:
Based on this codebase, what are the patterns or practices I should
definitely NOT use when adding new code? What would break the existing patterns
or create problems with the established conventions?
This question systematically surfaces the footguns before you step on them.