6.1
Reading A System You Didn't Build
Why this exists
Everything up to now, you built. You knew where things were because you put them there.
That ends here. From this lesson on, you're working on systems somebody else made, that were running before you arrived, and that nobody has time to explain to you. This is the actual job, and the skill it needs — walking into unfamiliar code and getting oriented fast — is the one nobody teaches because everyone assumes you'll pick it up.
The idea
You don't read a system. You interrogate it — and you have something that reads faster than you do.
The instinct is to open files and start reading top to bottom. Don't. A real system is too big, and reading it linearly tells you what the code says without telling you what it's for.
Instead, get the map first, in this order:
| Question | How you get it |
|---|---|
| What is this for? | README, or ask Claude to infer it |
| Where does it start? | The entry point — what runs first |
| What does it touch? | Databases, APIs, other services |
| What changes most? | git log — churn shows you where the action is |
| What would break it? | Ask directly |
That fourth one is underrated. Recent git history tells you where a system actually lives. Files touched twenty times this month are the working parts. Files untouched for two years are either stable or dead, and knowing which is a good question to ask.
The move that makes this fast: point Claude at the repo and ask it to explain the system to you as if you're new. That's a genuinely good use of it — reading a lot of code and summarising structure is exactly what it's good at, and you can check what it tells you.
Which you must. Everything from 2.1 applies here with full force: it will describe the system confidently whether or not it understood it. So you verify the way you verify anything — pick three specific claims and go look at the actual file.
The test of understanding is whether you can explain it to someone else. Not whether you feel like you get it. Write it down. The gaps show up in the writing, and the written version is worth something later — to you in a month, and to whoever arrives after you.
One honest expectation: an hour gets you a map, not mastery. That's the correct outcome. You want to know enough to ask a sharp question and to know which parts you shouldn't touch yet.
Do
Use a repo you genuinely didn't write. An open-source project, or something internal you've never opened.
- Don't open any files yet. Point Claude Code at the repo and ask: "Explain this system to me as if I'm new. What is it for, where does it start, and what does it depend on?"
- Write down its answer.
- Verify three specific claims. Pick three things it said and open the actual files. Note whether they match.
- Run
git log --oneline -30. What's been changing? - Find the churn — which files change most:
bash git log --format=format: --name-only | sort | uniq -c | sort -rn | head -15 - Ask: "What's fragile here? What would you not touch on your first day?"
- Write
system-map.mdin your own words: what it's for · where it starts · what it touches · what changes most · what you'd be careful with. - End with three questions you can't answer from the code. Those are the ones worth asking a human.
Step 8 is the mark of doing this well. Knowing what you don't know is more useful than a confident summary with holes in it.
Done when
Never do
Don't change anything on a first read. You're building a map. A map is not permission. The next three lessons are about how to touch things safely, and they come after this one for a reason.
Don't trust the explanation without checking it. A confident, wrong map of a system you're about to be responsible for is worse than no map — you'll act on it.