Code Exploration¶

Learn how to navigate and understand unfamiliar codebases with Claude Code.

What You'll Learn¶

Strategies for exploring new projects
Finding files, functions, and patterns
Understanding architecture
Tracing code flow

The Exploration Mindset¶

When you encounter a new codebase, you need to understand: 1. Structure - How files and folders are organized 2. Architecture - How components interact 3. Conventions - Patterns and standards used 4. Entry points - Where execution begins

Claude Code can help with all of these.

First Contact: Project Overview¶

When you open a new project, start broad:

> Give me an overview of this codebase

Claude will: - Read key files (package.json, README, etc.) - Scan the directory structure - Identify the tech stack - Summarize the project's purpose

More Specific Overviews¶

> What technologies and frameworks does this project use?

> Describe the folder structure and what each folder contains

> What are the main entry points to this application?

Finding Files¶

By Name Pattern¶

> Find all TypeScript files in src/

> Where are the test files located?

> Find files that contain "auth" in the name

By Content¶

> Find all files that import from 'lodash'

> Which files define React components?

> Find where the DATABASE_URL environment variable is used

By Purpose¶

> Where is user authentication handled?

> Which file defines the API routes?

> Find the database connection code

Understanding Code¶

Function Deep-Dive¶

> Explain what the processPayment function does step by step

Claude reads the function and explains each part.

Tracing Execution¶

> Trace what happens when a user clicks the "Submit" button

Claude follows the code path from UI to backend.

Dependency Mapping¶

> What does UserService depend on?

> What files import the utils/format.js module?

> Show me the dependency tree for the auth module

Architecture Questions¶

High-Level¶

> How is this app architected? Is it MVC, microservices, etc.?

> How does data flow from the frontend to the database?

> What's the request lifecycle in this Express app?

Specific Patterns¶

> How is state managed in this React app?

> What design patterns are used in the services folder?

> How does error handling work throughout the app?

Integration Points¶

> What external APIs does this app connect to?

> How does the app handle authentication?

> Where does caching happen?

Practical Exploration Sessions¶

Session 1: Understanding a Bug¶

> The /api/users endpoint returns 500 errors intermittently.
  Help me trace the code path and find potential issues.

Claude examines: - Route definition - Controller logic - Database queries - Error handling

Session 2: Adding a Feature¶

> I need to add email notifications. First, help me understand
  how notifications currently work in this app.

Claude finds: - Existing notification code - Patterns used - Where to add the new feature

Session 3: Onboarding¶

> I just joined this project. Walk me through the codebase
  as if you're onboarding me.

Claude provides: - Project overview - Key concepts - Important files - Development workflow

Search Strategies¶

When You Know the Term¶

> Find all occurrences of "deprecated" in the codebase

> Search for TODO comments

> Find all console.log statements

When You Know the Pattern¶

> Find all functions that start with "handle"

> Find all React hooks (useSomething pattern)

> Find all async functions

When You Know the Intent¶

> Find where user passwords are hashed

> Where is the JWT secret defined?

> Find the rate limiting configuration

Reading Complex Code¶

Ask for Annotations¶

> Read src/core/engine.js and add comments explaining
  what each section does (don't modify the file, just show me)

Request Simplification¶

> Explain this regex in plain English:
  /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$/

Get Visual Representations¶

> Draw an ASCII diagram showing how these components interact:
  - AuthController
  - AuthService
  - UserRepository
  - JWTUtils

Building a Mental Map¶

Document Your Findings¶

> Based on our exploration, create a brief architecture
  document for this codebase

Ask Clarifying Questions¶

> I'm confused about the difference between 'services' and
  'controllers' in this project. Explain the distinction.

Validate Understanding¶

> Let me verify: when a user logs in, the flow is:
  1. AuthController receives request
  2. AuthService validates credentials
  3. JWTUtils creates token
  Is this correct?

Try It Yourself¶

Exercise: Explore an Open Source Project¶

Clone a popular open source project:

git clone https://github.com/expressjs/express.git
cd express
claude

Get oriented:

> Give me an overview of the Express.js codebase

Find specifics:

> Where is the router defined?

> How does middleware work?

Trace execution:

> What happens when I call app.get('/path', handler)?

Document findings:

> Summarize what I've learned about Express internals

Exercise: Code Review Preparation¶

Pick a file in your own project
Ask Claude to explain it as if to a new team member
Ask about edge cases and potential issues
Ask what tests should exist for this code

Pro Tips¶

Start Broad, Go Deep¶

Don't dive into details immediately. Understand the landscape first.

Use Multiple Passes¶

First pass: What files exist? Second pass: What do they do? Third pass: How do they connect?

Save Context¶

Use /compact periodically to save your exploration context.

Ask "Why" Not Just "What"¶

# What
> What does this function do?

# Why (more valuable)
> Why is this implemented as a singleton pattern?

What's Next?¶

Now that you can explore codebases, learn how to debug effectively in 02-debugging.

Summary: - Start with broad overviews, then dive into specifics - Claude can find files by name, content, or purpose - Trace code execution to understand flow - Ask architectural questions to understand the big picture - Build a mental map through iterative exploration

Learning Resources¶

Featured Video¶

Edmund Yong: 800+ Hours Learning Claude Code (Popular tech channel)

Learn codebase exploration techniques with Claude Code including search patterns and architecture analysis.

Additional Resources¶

Type	Resource	Description
🎬 Video	MCP Workflows Tutorial	All About AI - Codebase navigation
📚 Official Docs	Agent Documentation	Subagent exploration patterns
📖 Tutorial	Builder.io Guide	Real-world exploration examples
🎓 Free Course	Anthropic Academy	Official courses
💼 Commercial	AI Coding Course	Codebase analysis techniques