Exploring a Codebase

Ask effective questions about unfamiliar code

Use @ to reference files and directories directly

Find relevant code for features and bugs

Trace execution flows through a codebase

Build understanding without reading every file yourself

One of the best uses of Claude Code is exploring code you did not write. Whether you joined a new team, inherited a project, or need to understand a library, Claude Code can be your guide. You ask questions, and Claude reads the files to give you answers.

This is different from searching documentation or reading code yourself. Claude Code looks at your actual files, not generic information. When it explains how authentication works, it describes your authentication system, not authentication in general.

This lesson teaches you how to ask good exploration questions, reference specific files, and trace how code flows through your project. By the end, you will be able to understand new codebases faster than ever.

When you first encounter a codebase, start broad. Claude Code can give you a high-level picture before you dive into details.

Good starting questions:

Claude reads key files like README.md, package.json, and main source files to summarize the project's purpose.

Claude identifies frameworks, libraries, and tools from configuration files and import statements.

Claude describes how the project is organized and what each major directory contains.

Claude finds where the application starts, whether that is a main function, an index file, or a server startup script.

These broad questions give you orientation. You understand what you are looking at before examining specific parts.

Follow-up questions:

Once you have the overview, go deeper:

Claude traces through files to answer these questions. It might read multiple files and explain how they connect.

Sometimes you know exactly which file you want Claude to examine. The @ symbol lets you reference files directly:

When you use @, Claude reads that file immediately. It does not have to search for it. This is faster and more precise.

File references:

Claude reads and analyzes this specific file.

Directory references:

Claude shows the directory listing and can summarize what each file does.

Multiple references:

You can reference multiple files in one question.

Relative and absolute paths:

Both work. Use whatever is most convenient:

When you reference a file with @, Claude Code also loads any CLAUDE.md files in that file's directory and parent directories. This ensures project context is included.

Often you do not know which files matter. You describe what you are looking for, and Claude finds it.

Finding code by feature:

Claude searches for files with relevant names, imports, and code patterns.

Finding code by pattern:

Finding code by error:

Claude searches for where this error message is defined or thrown.

The key is describing what you are looking for in plain terms. Claude translates your description into file searches and code analysis.

Understanding code often means tracing how data or control flows through the system. Claude Code can follow these paths.

Request flows:

Claude walks through the code from the login form to authentication to session creation.

Data flows:

Error flows:

These questions ask Claude to read multiple files and explain the connections. The answers show you how pieces fit together, not just what individual files contain.

Beyond specific code, you can ask about design decisions and patterns:

Claude identifies architectural patterns by examining how code is organized and how components interact.

Comparing to standards:

Claude can evaluate code against common standards and point out deviations.

These patterns make exploration more effective:

Start broad, then narrow. Begin with overview questions, then zoom into specific areas. This builds context that makes detailed questions more useful.

Use @ when you know the file. Direct references are faster than making Claude search. If you know the file name, use it.

Ask about connections, not just files. Questions like "how do these work together" reveal more than "what does this file do" asked twice.

Let Claude build context. Early questions help Claude understand the codebase. Later questions benefit from this understanding. Do your exploration in one session when possible.

Trust but verify. Claude's explanations are based on actually reading your code. But for critical understanding, follow up by reading the key files yourself.

Start exploration with broad overview questions about purpose and structure

Use @ to reference specific files when you know what to examine

Ask Claude to find relevant code when you do not know file names

Trace execution flows to understand how code works together

Build understanding incrementally from broad to specific

Claude reads your actual code, not generic documentation

Explore a codebase with these steps:

Open Claude Code in a project you are not fully familiar with.

Ask "what does this project do?" and read the overview.

Ask "what technologies does this project use?"

Ask "explain the folder structure."

Pick a feature and ask "how is [feature] implemented?"

Find a specific file using @ and ask for explanation.

Ask Claude to trace a flow: "trace what happens when [action]."

Ask an architecture question: "what patterns does this code use?"

By the end, you should understand the project significantly better than when you started.

https://code.claude.com/docs/en/common-workflows - Codebase exploration workflows

https://code.claude.com/docs/en/best-practices - Effective prompting patterns for exploration

https://code.claude.com/docs/en/quickstart - Basic exploration questions