Claude Code & Agentic Development · Lesson 2

How Claude Code Reads a Codebase

Understand how the agent samples files, respects CLAUDE.md and .gitignore, navigates large repos, and uses include/exclude.

20 min read4 questions in quizReady prompt includedIn progress

Practical exercise

What to do after this lesson

In a large repo, ask Claude Code to describe the architecture without naming files. Then restart with --include on one directory and --exclude on tests, ask the same question, and compare how much sharper and faster the answer is.

Task grader

In a large repo, ask Claude Code to describe the architecture without naming files. Then restart with --include on one directory and --exclude on tests, ask the same question, and compare how much sharper and faster the answer is.

Your answer

Ready-to-use prompt

Template for this lesson

Copy and adapt to your context. Text in angle brackets should be replaced.

The repository is large; I need a map, not a retelling of everything.
I'm interested in the subsystem: <name/folder>

First describe only the high-level structure (entry points, layers, key files).
Then drill into ONLY that subsystem and show the call chain.
Do not read tests or generated code.

Prompt sandbox

Prompt

Common mistakes

What people get wrong

What the agent sees at start

Claude Code does not load the whole repository into context up front. Instead it:

Reads CLAUDE.md from the root (and nested folders) — this is the first thing in context.

Respects .gitignore — node_modules, .next, dist and so on are not indexed.

Samples the structure: looks at the file tree, opens what's relevant to your request as needed (lazy reading).

So in a giant monorepo the agent doesn't drown: it pulls files in on demand for the task.

Asking about architecture

A good first request in an unfamiliar project:

Describe the architecture: where the entry point is, how layers are organized, where the business logic and DB access live. Name the key files.

The agent walks the tree, opens entry points, configs, the DB schema, and gives you a map. Then drill down into specific modules.

Narrowing scope: include / exclude

When the repo is large or has noisy directories, limit the scope:

claude --include "src/**" --exclude "**/*.test.ts" --exclude "legacy/**"

--include — allowlist of paths where the agent may work and read.

--exclude — blocklist: generated code, vendored deps, legacy you must not touch.

This both speeds things up and reduces the risk of the agent editing the wrong thing.

Large repositories in practice

Ask about the high-level structure first, then drill down — don't ask "read the whole project".

Name concrete paths and modules in the request — this sharply cuts unnecessary reading.

Keep an up-to-date CLAUDE.md with a project map (next lesson): the agent orients without re-scanning.

.gitignore is your friend: if build artifacts and caches are in it, the agent won't touch them.

Report a bug

How Claude Code Reads a Codebase

Task grader

Prompt sandbox

Quiz — 4 questions

Discussion

What the agent sees at start

Asking about architecture

Reading multiple files at once

Narrowing scope: include / exclude

Large repositories in practice

Why this matters