Exploring an unfamiliar codebase
The thing agents are genuinely better at than you — if you stop them from summarising instead of reading.
Reading unfamiliar code is tedious, and tedium is exactly where a tireless reader beats a human. But the default behaviour is bad: asked to explain a codebase, most agents read three files, pattern-match to projects they saw in training, and produce a confident architecture description that is 70% right. You measured this in Lesson 1.5.
The fix: make it trace something specific
Do not ask "how does this codebase work". Ask it to follow one concrete path end to end. A trace forces reads, and reads produce primary sources.
Trace what happens when a user submits the checkout form, from the HTTP handler to the database write. For each step, give me: file path, the function, and the 1-3 lines that pass control to the next step. Quote them. If you cannot find the next step, say where you looked and stop. Do not describe anything you have not read.
The "quote them" and "say where you looked and stop" clauses do the real work. They make gaps visible instead of letting the model bridge them with plausible invention.
Four traces that map most systems
- The main request path. Entry point to persistence, as above.
- The startup path. What runs before serving: config loading, migrations, dependency wiring. This is where the surprising constraints live.
- The test path. How does one test actually run — what gets mocked, what gets a real database, how is state reset? You need this before you can ask for tests.
- One recent bug fix. Pick a commit, ask the agent to explain the bug and why the fix works. It teaches you the failure modes the codebase actually has.
Then ask the questions maps do not answer
Based only on files you have read in this session: 1. Where are there two different ways of doing the same thing? 2. Which module would be riskiest to change, and what evidence in the code tells you that? (test density, fan-in, comments, error handling) 3. What convention does the code follow that is not written down anywhere?
Question 3 is the valuable one. Unwritten conventions are precisely what an agent will violate by default and precisely what you will encode in Module 05.
Watch out
Exploration is expensive context. A thorough trace can cost 30–60k tokens, which is most of your smart zone. Do exploration in its own session, write down the conclusions, then clear before doing any work. Exploring and implementing in one session is the classic way to be deep in the dumb zone before you write a line.
Try it
Run the main-request trace on your practice repo. Verify three of the quoted line references yourself. Then write a 15-line summary of what you learned, in your own words, and save it — it is the seed of your project brief.
Takeaways
- Ask for a traced path with quoted lines, not an architecture summary.
- Require the agent to stop at gaps rather than infer across them.
- Explore in a dedicated session; save conclusions and clear before implementing.
Why does "do not describe anything you have not read" change the output so much?
It converts the task from generation to retrieval. Without it, the model fills gaps from parametric knowledge because a complete-sounding answer is the likely continuation. With it, gaps become visible — and a visible gap is something you can go look at.
A course by Pieter Zandbergen