Lesson 3 12 min

Understanding Codebases with AI

Learn to navigate unfamiliar codebases quickly using AI — from high-level architecture to finding the exact file you need to modify for your contribution.

🔄 Recall Bridge: In the previous lesson, you learned how to find beginner-friendly projects and evaluate their health. Now you’ve found a project and cloned it — but it’s 500 files of unfamiliar code. Let’s navigate it.

Understanding an unfamiliar codebase is the skill that separates productive contributors from people who clone a repository and give up. AI turns this from a multi-day struggle into a focused 30-minute exploration.

Level 1: Get the Big Picture

Before diving into files, understand the project’s architecture.

AI prompt for high-level overview:

I cloned [PROJECT NAME]. Here’s the directory structure: [PASTE OUTPUT OF tree -L 2 OR ls -R]. Explain: (1) What does this project do? (2) What’s the architecture (monolith, microservices, MVC, etc.)? (3) Where does the main entry point live? (4) How is the code organized — what goes in each top-level directory? (5) What frameworks and libraries does it use?

This gives you a mental map. You now know whether src/ contains the application code, lib/ has shared utilities, and tests/ mirrors the source structure.

Level 2: Trace the Data Flow

Most bugs and features live along a data flow path — a request comes in, gets processed, and produces output. Tracing this flow tells you exactly which files matter.

AI prompt for flow tracing:

In this codebase, trace how a [SPECIFIC FEATURE] works from start to finish. For example: “How does a user login request flow from the HTTP endpoint to the database and back?” Show me: (1) Which file receives the request, (2) What middleware/interceptors it passes through, (3) Which service/function processes the logic, (4) How it interacts with the database, (5) What gets returned to the client. Include file paths for each step.

Example output you’d get:

Step	File	What Happens
1. Route	`src/routes/auth.ts`	POST /login endpoint defined
2. Validation	`src/middleware/validate.ts`	Request body validated against schema
3. Service	`src/services/auth.service.ts`	Password checked, JWT generated
4. Database	`src/models/user.model.ts`	User looked up by email
5. Response	`src/routes/auth.ts`	JWT token returned to client

Now you know exactly which files to read — and more importantly, which files you can ignore.

Level 3: Understand Project Patterns

Every project has patterns — recurring ways of doing things. Understanding these patterns is what makes your contribution look like it belongs.

AI prompt for pattern extraction:

Look at these 3 files from the project: [PASTE 3 SIMILAR FILES, e.g., 3 API route handlers]. What patterns do they follow? Specifically: (1) How are routes/endpoints structured? (2) How is error handling done? (3) How is input validated? (4) What naming conventions are used (files, functions, variables)? (5) How are responses formatted? (6) If I’m adding a new [ENDPOINT/FEATURE], what template should I follow to match these patterns?

Common patterns to identify:

Pattern	What to Look For	Why It Matters
Error handling	Try/catch structure, error types, response format	Your code must handle errors the same way
Naming conventions	camelCase vs snake_case, file naming, test naming	Inconsistency triggers reviewer comments
Import style	Relative vs absolute, import order	Linting may enforce this automatically
Testing approach	Unit vs integration, mock strategy, fixture patterns	Tests must match existing style
Code organization	Where logic lives (controller vs service vs model)	Put your code in the right layer

Level 4: Find Where to Make Your Change

You understand the architecture and patterns. Now find the exact location for your change.

AI prompt for locating your change:

I need to [DESCRIBE YOUR CHANGE — e.g., “add email validation to the registration endpoint”]. Based on the project’s architecture, which files do I need to modify? For each file, explain: (1) What change is needed, (2) What existing code to modify vs. what new code to add, (3) What tests I need to write or update. Also flag any files I might miss — for example, do I need to update an index file, a type definition, or a configuration?

✅ Quick Check: You’re about to fix a bug in a Node.js project. AI tells you the bug is in src/utils/format.js line 42. Before changing that line, what else should you check? (Answer: Check the test file — usually tests/utils/format.test.js or similar. If a test already covers this case and passes, the bug might be elsewhere. If no test covers it, you’ll need to add one. Also check git blame on that line — the commit message might explain why it was written that way, and changing it might break something intentional.)

Practical Workflow: Your First 30 Minutes

Minute	Action	AI Prompt
0-5	Clone and scan	“Explain this directory structure”
5-10	Read README + CONTRIBUTING	“Summarize contribution requirements”
10-15	Trace the relevant flow	“How does [feature] work end-to-end?”
15-20	Study patterns in related files	“What patterns do these files follow?”
20-25	Locate your change	“Which files do I need to modify for [change]?”
25-30	Read the specific code	“Explain this function and its edge cases”

After 30 minutes, you should understand enough to start making your change confidently.

Key Takeaways

Start with the big picture (architecture, directory structure) before diving into files — AI can explain a project’s entire organization in seconds, giving you a mental map that prevents getting lost in hundreds of files
Trace data flows rather than searching for keywords — most bugs and features live along a request path (endpoint → middleware → service → database), and AI can map this entire chain with file paths so you know exactly which 5 files matter out of 500
Extract project patterns from existing code before writing your own — every project has specific conventions for error handling, naming, testing, and code organization, and contributions that match these patterns get accepted faster because they look like they belong

Up Next

In the next lesson, you’ll master the Git workflow for open source contributions — forking, branching, committing, and creating pull requests the way maintainers expect.

Knowledge Check

1. You cloned a large repository (500+ files) and need to fix a bug in the user authentication flow. You ask AI: 'Where is the authentication code?' AI suggests checking auth.py, middleware/auth.js, and services/authentication/. You find all three exist. What do you do next?

Pick the first file (auth.py) and start making changes — AI found it for you Trace the flow, not just the file. Ask AI: 'How does a login request flow through this codebase? Start from the HTTP endpoint and trace through middleware, service layer, and database call. Show me the call chain with file paths.' A bug in 'authentication' could live in any layer — the route handler, the middleware, the service, or the database query. Understanding the flow tells you WHERE in the chain the bug occurs. Then verify by reading the actual code AI pointed to — AI gives you a map, but you confirm the territory Search for the word 'login' across all files and read every match

2. You're reading a Python project and encounter this pattern in every file: `from app.core.deps import get_current_user`. You don't understand what `deps` means or why it's structured this way. How should you use AI?

Ask AI to rewrite the code in a pattern you're more familiar with Ask AI to explain the pattern in context: 'This project uses dependency injection via app/core/deps.py. Explain: (1) What is the dependency injection pattern and why is it used here? (2) What does get_current_user do and how is it used across the codebase? (3) If I'm adding a new endpoint that needs authentication, how should I use this pattern?' This teaches you the project's conventions so your contribution follows the same style. Understanding patterns > understanding individual files Ignore it — you don't need to understand every pattern, just the file you're changing

3. You've been reading a codebase for 2 hours with AI assistance. You now understand the architecture, the main patterns, and where your change should go. But you notice the project uses a testing framework you've never used (pytest with fixtures). What's the efficient approach?

Learn pytest from scratch before making any changes — you need to write tests Ask AI to explain how the project uses pytest specifically — not pytest in general, but THIS project's test patterns. Prompt: 'Show me 3 example test files from this project. Explain the test patterns used: how are fixtures defined, how is test data created, how are API endpoints tested? Then show me a template for writing a test that matches these patterns.' Learning the project's specific testing approach takes 15 minutes. Learning pytest from scratch takes hours and most of it won't apply to this project's conventions Skip writing tests — the maintainers can add tests if they think your change needs them

Answer all questions to check

Complete the quiz above first

Related Skills

Code Reviewer Pro Code Reviewer Pro