2.1 Exploring Codebases

Course: Claude Code - Essentials Section: Core Workflows Video Length: 2-5 minutes Presenter: Daniel Treasure

Opening Hook

You've just installed Claude Code and opened it in a project. But what if you don't understand what you're looking at? In this video, we'll explore how to let Claude be your guide through an unfamiliar codebase—reading structure, understanding architecture, and asking smart questions to get answers fast.

Key Talking Points

Ask Claude to Understand the Project First
Before making changes, always ask Claude to analyze what you're working with
Questions like "What does this project do?" or "Where's the main entry point?" get you oriented
Claude reads multiple files and summarizes the architecture
Show on screen: Ask a simple question and let Claude explore—no edits yet, just reading
The Power of Natural Language Questions
You don't need to manually search every file
Claude Code understands questions about code flow, dependencies, and design patterns
Examples: "How does authentication work in this project?" or "Where are the database queries?"
Show: Ask a question that requires understanding multiple files; Claude connects the dots
Using @-Mentions to Focus the Scope
Reference specific files or directories with @filename or @directory/
Narrows Claude's attention when the codebase is large
Example: @src/api what endpoints are exposed here?
Show: Use @ to reference a folder, then ask a targeted question
Reading Without Writing
Exploration is read-only; Claude shows you what's there
No file changes yet—this is safe discovery
Perfect for understanding before proposing changes
Show: Terminal output showing Claude's analysis without any Edit or Write tool calls
Building Context for Later Tasks
What you learn here becomes the foundation for 2.2 (making changes), 2.3 (git), and beyond
Claude remembers context in the session, so avoid re-explaining
A few smart questions now save you time in every future task
Show: Brief context summary in the conversation for reference

Demo Plan

Demo Project: A small, well-known open source project (suggest: a simple Node.js app like express-starter or next-auth-demo, or a Python project like flask-blog)

Setup (off-camera before video): - Clone or have a sample project ready - Open terminal - Run cd /path/to/project && claude to start a session

On-Camera Sequence (aim for 2-3 minutes of live demo):

First Prompt: Ask Claude to summarize the project What is this project? What technologies does it use?
Show Claude reading files and responding with a summary
Highlight that Claude is exploring without permission prompts (read-only)
~30 seconds
Follow-up: Ask about structure Where is the main entry point? How are routes/handlers organized?
Show Claude referencing specific file paths
Demonstrate that follow-up questions build on prior context
~30 seconds
Scoped Question with @-Mention: Focus on a specific area @src/database explain how the data models are defined
Show the @ autocomplete and how it narrows scope
Claude dives into that directory
~20 seconds
End with a Takeaway: Optionally show asking Claude a question you "need" answered for a future change How would I add a new user role to this system?
Claude provides guidance without making changes
Signal this analysis will help in upcoming videos (2.2, 2.4, etc.)
~20 seconds

Code Examples & Commands

Starting a session:

cd /path/to/your/project
claude

Example prompts to use:

What does this project do?
What's the main entry point?
Explain the folder structure.
How are the API routes organized?
@src/auth How does authentication work?
@components What React components are in this directory?
What would need to change to add X feature?

Using @-mentions:

@filename.js - Reference a single file
@src/components/ - Reference a directory
@package.json - Ask about dependencies
@README - Include the readme in context

Gotchas & Tips

Claude reads gitignore by default – Node_modules, .env files, etc. are usually excluded. This is intentional (saves tokens, avoids noise).
Larger codebases may need guidance – If Claude's response is vague, ask a more specific follow-up. "Which file contains the API handler?" narrows it down.
@ autocomplete saves time – Press Tab or start typing after @ to see available files and folders. Much faster than typing paths.
Session context is your friend – Claude remembers what you told it. Avoid repeating "This is a Node app" multiple times in the same session.
Read-only exploration doesn't require permissions – No approval prompts appear for exploring code. That changes in 2.2 when you make edits.
Large responses may truncate in terminal – If Claude's response is very long, you can ask "summarize that in 3 bullet points" or scroll back to read more.

Lead-out

Now that you understand your codebase, you're ready to make changes. In the next video, we'll show how Claude helps you edit files, add features, and refactor code—with your approval at each step. You'll use all this context you just learned.

Reference Material

Claude Code Quickstart (Getting Started section): https://code.claude.com/docs/en/quickstart
Common Workflows - Exploring Codebases: https://code.claude.com/docs/en/common-workflows
CLI Reference (@ mentions): https://code.claude.com/docs/en/cli-reference
VS Code Integration (@-mentions): https://code.claude.com/docs/en/vs-code

Relevant Articles & Posts

Official Docs: "Common Workflows - Claude Code Docs" (https://code.claude.com/docs/en/common-workflows)
Article: Joe Njenga's "17 Best Claude Code Workflows" (Medium) – covers exploration patterns
Resource: ClaudeLog - Claude Code Best Practices (https://claudelog.com/)

Additional Notes

Keep the tone conversational—you're showing how Claude becomes a "guide" through unfamiliar code
Pause after showing Claude's response to let viewers read the summary
Emphasize that exploration is safe (read-only, no approval needed)
Call attention to the session context continuing across multiple prompts
Use a real (but simple) project so viewers can follow along with their own code later

Quick Reference