Explore before you edit
When you drop into an unfamiliar repository, resist the urge to start changing things. Spend your first session asking questions. Claude reads files, traces calls, and inspects git history far faster than you can scroll, so let it build your mental model first. The prompts below move from the widest possible view down to the specifics you need before making a change.
Tip: Run these in plan mode (Shift+Tab twice) so the whole session stays read-only — perfect for pure exploration.
Get the big picture
Start wide. These prompts establish architecture, stack, and the path a request takes through the system:
> Give me a high-level overview of this codebase — architecture, main
components, and how they connect.
> What tech stack is this built on and what are the main third-party
dependencies?
> What does the data flow look like from an HTTP request to a database
write?Find specific code
Once you have the shape of the project, zoom in on the parts you care about:
> Where is authentication handled? Show me the flow from login request
to session creation.
> Find all the places we make external API calls and identify any that
don't handle errors.
> What's our database schema? Walk me through the main entities and their
relationships.Understand existing patterns
Before you write a single line, learn how this team writes code. Matching the existing conventions is what makes your changes blend in rather than stick out:
> What coding patterns does this codebase use? Are there consistent
conventions I should follow?
> How is error handling done throughout the project?
> Show me examples of how we typically write tests here.Before you make changes
Finally, scout the specific area you're about to touch and surface any landmines:
> Before I add a new endpoint, explain how existing endpoints are
structured.
> What are the known problem areas or technical debt in this codebase?
> Are there any TODOs or FIXMEs I should know about?Prompts from the official library
A few reliable starters worth keeping in your back pocket for any new repository:
- "Summarize the main purpose and architecture of this codebase."
- "Find the entry points and explain how the application starts."
- "List all external dependencies and what each one is used for."
Practice project
Clone an open-source project you've never seen before. Using only Claude Code prompts, write a one-page technical summary: its architecture, the patterns it follows, its key components, and a suggested onboarding order for a brand-new developer. You'll be surprised how quickly you can go from "no idea" to "I could fix a bug here."
Exploring Codebases FAQ
How do I use Claude Code to understand a new codebase?
Spend your first session asking questions instead of editing. Start wide with an architecture overview, then zoom in on specific features, learn the project's conventions, and scout the area you plan to change before touching any code.
Should I use plan mode to explore a codebase?
Yes. Press Shift+Tab twice to enter plan mode so the whole session stays read-only. That is perfect for pure exploration because Claude can read files, trace calls, and inspect git history without making any changes.
What should I ask Claude Code first about an unfamiliar project?
Start with the big picture: ask for a high-level overview of the architecture and main components, what tech stack and dependencies it uses, and what the data flow looks like from an HTTP request to a database write.
How do I find specific functionality in a codebase with Claude Code?
Once you have the shape of the project, ask targeted questions such as where authentication is handled, where external API calls are made and which lack error handling, and what the database schema and main entity relationships are.
Why should I explore a codebase before making changes?
Learning the existing conventions is what makes your changes blend in rather than stick out. Scouting problem areas, technical debt, and TODOs first helps you avoid landmines in the code you are about to touch.
Quick summary
- Explore before you edit — let Claude build your mental model first
- Work from the big picture down: architecture, then specific code, then patterns
- Learn the project's conventions so your changes blend in
- Scout problem areas and TODOs before touching the code you'll change