How Claude reads your codebase

When you give Claude Code a task that touches an existing project, the first thing it does is look around. This lesson is about what "look around" actually means — the specific tools Claude uses, what those tools can and can't see, and how knowing the mechanics makes you a sharper collaborator.

Claude doesn't read your whole project

A common misconception: Claude loads your entire codebase into its brain at the start of a session. It doesn't. Even with very large context windows, that's wasteful and slow. Instead, Claude reads files on demand — opening one, then another, then another, following a trail of what looks relevant.

That has two consequences:

• For trivial questions on big projects, Claude is fast because it only reads what it needs.
• For vague questions on big projects, Claude can wander — opening ten files trying to figure out where the relevant logic lives.

The fix for that wandering is mostly on you: be specific. Point at the right file, name the right function, narrow the question.

The core tools Claude uses to look around

There are three you should know about:

Read

Open a specific file by path. Read src/auth/login.ts. The contents come back, sometimes a chunk at a time if the file is huge. Simple and obvious.

Glob

Find files by pattern. Glob src/**/*.test.ts returns every test file under src/. This is how Claude discovers files when it doesn't know the exact name. The **means "any depth of folders."

Grep

Search file contents across the project for a pattern. Looking for every place a function named processPayment is called? Grep processPayment. Grep returns the file paths and the matching lines. This is the fastest way to find anything by text.

What Claude can't see

Important boundaries:

• Anything outside your working directory.Claude can't read your ~/Documents if you ran it in ~/Projects/my-site. The folder you start it in is the boundary.
• Hidden files inside the project are usually visible.Things like .env, .gitignore, and .git/can be read unless you've restricted them. This is important for secrets — never leave a .envwith real keys in a folder you're sharing with Claude unless you trust the session.
• The state of memory between sessions, by default.Each new session is fresh. Long-term context lives in CLAUDE.md(you'll meet it shortly) and the memory system (Module 4).

Why specificity in prompts saves time

Compare two requests:

Fix the bug with the login.

Claude has to do detective work: enumerate files (Glob), search for "login" (Grep), open candidates (Read), look for suspicious recent changes (git log), and then start guessing.

In src/auth/login.ts, the form submits twice when you press Enter — I think the keydown handler isn't calling event.preventDefault(). Take a look and fix it.

Claude reads one file, finds the handler, makes the fix. Five seconds instead of two minutes. Same code change, much less machinery in between.

Filling Claude in with CLAUDE.md

For longer-running projects, you don't want to keep re-explaining the structure. A file named CLAUDE.md at the root of your project gets read automatically at the start of every session. It's where you write "here's how this project is laid out, here are the conventions, here's what to avoid."

We'll devote a whole lesson to CLAUDE.mdshortly. For now, know that it exists and that it's the long-term memory for "what this project is and how it works."

Reading a session by the tool calls

When you watch a Claude Code session, the bits in between your messages and Claude's text replies are the tool calls. They'll look something like:

> Read src/auth/login.ts
> Grep "submit" src/auth
> Read src/auth/loginForm.ts
> Edit src/auth/loginForm.ts (12 lines changed)

That tells the whole story: Claude opened the main file, searched for "submit" across the folder, opened the form file that came up, and edited it. You can follow the investigation without reading any code yourself.