Your first real read

You’ve covered the ideas. Time to do the thing.

This lesson mirrors Lesson 1.10 and Lesson 2.8: no new theory, just a run-through where every move from Level 4 gets used at least once. Open a real terminal. Actually type the commands.

Pick a codebase

You want a project with at least a few files and some actual structure. Pick one of:

A project you’ve been working on — even a small side project counts.
A project from your team — if you’ve got access to a real codebase you’ve never really read, that’s perfect.
An open-source project from GitHub — even better for practice, because nothing’s familiar. Some good small ones to clone: a static site, a CLI tool, a Python script you’ve used. Pick something under ~50 files for this lesson. (You can do bigger ones later — Claude scales further than this exercise will.)

If you’re going with an open-source repo, clone it into a folder:

cd ~
git clone <some-repo-url> my-practice-repo
cd my-practice-repo

Then start Claude in there:

claude

Take a breath. You’re about to learn a codebase you’ve never seen, in five questions.

Move 1 — Orient

The first question you always ask. Don’t overthink it:

what is this project? Read README.md and the top-level files, and give me a short summary.

Watch the turn loop you learned in Lesson 2.4: thinking → tool → output → answer. Claude will read the README, glance at package.json or its equivalent, and tell you:

What the project is.
What language and framework it uses.
How to run it.
The shape of the folder structure.

That’s your orientation. You’re no longer staring at a stranger.

Move 2 — One file, asked sharply

Pick a file from the answer that sounds interesting. The one you’d be most curious about. Now use the move from Lesson 4.2:

walk me through src/<that-file>. What does it do, and how is it structured?

You’re going from a 30,000-foot view to a single ground-level building. Read Claude’s answer carefully — you should now know, in one or two sentences, what that file’s job is in the project.

Move 3 — One symbol, by name

In that answer, you’ll see function or component names. Pick one whose job isn’t obvious. Now apply Lesson 4.3:

explain <function-name>. What does it do, and what does it call?

You don’t need to know where it lives anymore. You just know its name. Notice how naturally curiosity drops from file → function → call.

Move 4 — Trace

Pick the most interesting call in that function’s answer — “it calls processData()” — and trace it. Use Lesson 4.4:

where is processData called from, and where does its input come from? Trace it.

Now you’re building a real mental map. You’ll get back something like: “called from two places, both in src/pipeline/; its input comes from a config file loaded at startup.”

In four questions, you’ve gone from “never seen this repo” to “I can sketch how this slice of it works.” That used to take half a day.

Move 5 — Verify

Now you stress-test the answers. Pick the most load-bearing claim from any of Claude’s responses — “this function is called from pipeline.ts” or “this value comes from .env”. Apply Lesson 4.7:

quote the exact line where processData is called in pipeline.ts.

Then open pipeline.ts (or cat it from another terminal) and confirm the line is really there, really says that.

If it checks out: you can trust the broader picture. If it doesn’t: ask Claude to look again, and tell it what you found. This is the moment you stop being someone who reads with Claude and start being someone who reads with Claude well.

Optional — the bonus moves

You’ve got time. Try one of these:

Read an error. Find a way to make the project break — type a command wrong, edit a file to introduce a typo, run the wrong script. Catch the resulting error and paste it into Claude (Lesson 4.5). Watch it translate.

Read the history. Pick any file you’ve been looking at and ask (Lesson 4.6):

what has changed in this file in the last few months, and why?

You’ll get a tour of the evolution of the file — sometimes more revealing than the file itself.

When you’re done

Exit Claude (Ctrl + C twice). Look around. The project that was unfamiliar 20 minutes ago has shape now. You couldn’t draw all of it, but you could draw the slice you investigated — accurately, with the names of real files and real functions in it.

That’s the win. Not “I understand the whole codebase.” That’s a goal that doesn’t exist. The real goal is “I can answer any specific question about this codebase, by reading with Claude.” You can.

What’s next

Level 5: Build with Claude. The training wheels come off again, and this time they come off for real — you’ll make your first real change to a codebase. Everything you just learned about reading is the foundation for changing things well. If you can read it, you can change it. If you can’t read it, don’t.