The Secret Life of Claude Code: Reading Code You Didn't Write
.jpeg)
The Secret Life of Claude Code: Reading Code You Didn't Write
How to orient yourself in an unfamiliar codebase — and how Claude Code can help you find your footing without losing your judgment
#ClaudeCode #CodingWithAI #SoftwareEngineering #DeveloperLife
Margaret is a senior software engineer. Timothy is her junior colleague. They work in a grand Victorian library in London — the kind of place where inherited collections are treated with respect, and where no one pretends to have read something they haven't. Timothy has arrived today with someone else's problem.
Episode 6
The Inheritance
He set the printed file listing on the table without saying anything. Margaret looked at it the way she sometimes looked at things — unhurried, reading from the top.
It was long.
"Whose is it?" she said.
"It was Marcus's. He left in February. It's a billing integration — handles subscription renewals, proration calculations, payment retries, webhook processing." He paused. "There's no documentation. There are comments, but most of them describe what the code does, not why it does it."
"And you need to do what with it?"
"Add support for a new payment provider. The product team wants it by end of month."
Margaret was still looking at the file listing. "How long have you been staring at it?"
"Since Monday."
"And today is Thursday."
"Yes."
She set the paper down. "Tell me what you've understood so far."
"The entry point is clear. The webhook handler is clear. But somewhere in the middle there's a proration engine that I genuinely cannot follow. The variable names are... interpretive. There are functions that call other functions that seem to call back into the first ones." He looked at her. "I don't know where to start."
"You started in the wrong place," Margaret said. "That is what we are going to talk about today."
Why Unfamiliar Code Resists Reading
"Most developers," Margaret said, "approach unfamiliar code the way they approach a novel someone has left open to page 200. They try to understand the page they're on. They get confused because they lack context. They flip back a few pages, get more confused, and conclude that the code is badly written."
"It might be badly written."
"It might be," she allowed. "But that conclusion comes later. First you need to read it properly." She picked up her pen. "There are two fundamental mistakes people make with unfamiliar code. The first is starting in the middle. The second is trying to understand everything before understanding anything."
Timothy looked at the file listing. "I did both."
"Most people do. The proration engine that's confusing you — do you know yet whether it's actually complex, or whether it only feels complex because you don't know what it's supposed to do?"
He was quiet for a moment. "I don't know."
"That is the correct answer," Margaret said. "And it tells you something important. You cannot evaluate code you don't yet have a model for. Before you try to read the proration logic, you need to understand what proration is doing in the context of this system. Not the code. The behaviour."
The Two Passes
"Before you open the code," Margaret said, "you make two passes. Most developers skip both of them and pay for it."
She turned the notepad toward him.
"The first pass is the map pass. You are not reading code. You are reading structure. File names. Directory organisation. The top-level shape of things. Function names — not their bodies, just their names. What does this codebase think is important? What are its concepts? What are the things it has chosen to name?"
"I did look at the file names."
"Did you write them down?"
He hadn't.
"Write them down," Margaret said. "Build a vocabulary. If you see prorateCharges, applyCredit, calculateMidCycleDelta — those are concepts. Before you read a single line of implementation, you should be able to describe the system in its own language." She paused. "This is where Claude Code becomes genuinely useful. Not to read the code for you. To help you build the map."
"How?"
"You paste in the structure. The file names, the function signatures, the class names. You say: based on these names and the organisation of this codebase, describe what you think this system does, what its main concepts are, and what questions you would want to answer before adding a feature to it. What you get back is not a definitive answer. It is a hypothesis — a starting model that you will test and refine as you read."
Timothy wrote this down carefully.
"The second pass is the flow pass. You pick one complete path through the system — one transaction, one webhook event, one renewal — and you follow it from entry to exit. Not everything. One thing. You are tracing a thread, not reading a book."
"And Claude Code?"
"The same way. Paste in the relevant files, describe the path you are trying to follow, and ask: what is this code doing along this path, and where does the path go? Again — a hypothesis. You are building a model, not receiving a verdict."
The Hypothesis Model
"I want to be precise about something," Margaret said. "When you use Claude Code to read unfamiliar code, it is giving you a hypothesis, not a fact. It reads what is there. It does not know why decisions were made. It does not know what requirements existed that no longer exist. It does not know what the comment above the function originally said before someone updated the code without updating the comment."
"It reads the code as it is."
"Exactly. Which is more than you have right now, but less than the full picture." She looked at him steadily. "This is the discipline. You take what Claude Code gives you, and you treat it as a starting point for questions, not as answers. If it says this function calculates proration by comparing the days remaining in the billing cycle to the total days, your response should not be great, I understand proration now. Your response should be: is that the right way to calculate proration for this product's billing model, and does the code actually do that consistently?"
"Test it against the actual code. Run it with real inputs. Find the edge cases the reading doesn't reveal. Claude Code can help you generate those tests — given this proration logic, what inputs would expose incorrect behaviour? But you are the one who decides whether the tests are asking the right questions."
What to Do With the Middle
"The middle," Timothy said. "The part I can't follow. What do I do with that specifically?"
"The middle is always the hardest part," Margaret said, "because by the time you get there, the code assumes you have context you don't have. You are missing the vocabulary of decisions — why things were done the way they were done." She set down her pen. "There are three things you can do."
"First — trace from the known. You said the webhook handler is clear to you. Start there. What does the webhook handler call? Follow that one call. Not where it leads eventually — just the immediate next step. Build the understanding one function at a time from a place of stability."
Timothy was nodding slowly. He had been trying to understand the middle in isolation.
"Second — read the tests. If there are tests — and Marcus, to his credit, wrote tests — they are documentation. They describe behaviour from the outside. A test that says when a subscription upgrades mid-cycle, the prorated charge should equal the per-day difference times the remaining days tells you more about the intention than the implementation does."
"Marcus did write tests," Timothy said. "I glanced at them."
"Don't glance at them. Read them. They are the clearest statement of what the code was meant to do." She allowed a brief pause. "And when you take those tests to Claude Code — not the implementation, the tests — and ask: what behaviour do these tests define, and are there cases they don't cover? — you get something valuable. You get an independent read of the specification."
"And the third thing?"
"Accept that some parts of the middle will not be clear until you have changed something." She looked at him. "There is a limit to understanding from reading. At some point you have to make a small, reversible change in a local environment with the test suite running, watch what breaks, and let the breakage teach you what the reading couldn't. This is not guessing. It is disciplined experimentation — but only ever against a test harness, never against code whose effects you cannot roll back. In a billing system especially, the cost of an uncontrolled experiment is not a failed build. It is a customer's incorrect charge."
He wrote that down without being asked.
"You form a hypothesis — this function is responsible for x — you make a change that would expose whether that hypothesis is correct, and you observe the result. The test suite is your safety net. Do not experiment without it."
The Question of Trust
"How much do I trust the code?" Timothy asked. It was the question that had been sitting under everything else.
Margaret considered it. "You trust it the way you trust a map of a city you've never visited. It is likely to be mostly accurate. It may be out of date in places. There may be roads that exist that aren't on the map, and roads on the map that no longer exist. You use it to navigate, but you look up from it."
"And Claude Code's reading of the code?"
"The same. More useful than nothing. Less authoritative than understanding you've built yourself." She picked up her tea. "Here is what I would say to you about trust, specifically. The code that is easy to follow — trust it provisionally and verify the edge cases. The code that is hard to follow — do not trust it at all until you understand why it's hard to follow."
She set the cup down carefully.
"Hard to follow code is sometimes cleverness — a developer who knew the language very well and optimised for terseness. It is sometimes the accumulated residue of decisions that made sense at the time, layered over years until the original shape is no longer visible. It is occasionally a genuine mistake that no one caught because no one wanted to look at it too closely." She paused. "And in billing systems specifically, it is sometimes none of those things. It is compliance. Tax law varies by jurisdiction. Payment processors impose constraints that have no business logic explanation. PCI requirements leave fingerprints in code that look arbitrary until you know what they're protecting against. Before you decide that something strange is a mistake and should be refactored — find out whether it was strange for a reason."
"How do I find that out?"
"The commit history," Margaret said. "Which brings me to something I should have said earlier."
Before He Left
Outside, a London afternoon was doing what London afternoons often do — persisting with determined neutrality, neither quite grey nor quite clear.
"You said I started in the wrong place," Timothy said. "Where should I have started?"
"At the beginning," Margaret said. "Not the beginning of the file. The beginning of your understanding." She looked at him. "You should have spent the first day not reading the code at all. Reading what the system does. The product documentation, if there is any. Then the commit history — not just the messages, but the pattern of them. Which files change together. Which functions have been touched repeatedly. A file that has been modified fifteen times in two years is trying to tell you something. A function whose commit message says hotfix: edge case for annual subscribers in EU is carrying context that the code itself cannot."
"I didn't look at any of that."
"Pull requests are the same. When Marcus opened a PR for a change to the proration engine, the conversation in that PR — the questions the reviewers asked, the justifications Marcus gave, the back-and-forth before it was merged — that is the documentation that never made it into the comments. Most developers never read it. It is the closest thing to sitting next to the person who wrote the code."
"That's all there, in the repository."
"All of it," Margaret said. "And Claude Code can help you make sense of it — paste in a commit thread or a PR description and ask: what problem was this change trying to solve, and what assumptions does it make? The history is a record of decisions. Decisions have reasons. The reasons are what you need."
He gathered his things slowly, the way he did when he was still processing something.
"One more thing," Margaret said. "When you do understand it — when you've built the model and tested it and you feel confident — write it down. Not for Marcus, and not for yourself. For the person who inherits this code from you."
She looked at him steadily.
"Because they will be standing exactly where you are standing now. And they will deserve better than three days of confusion before they find their footing."
He closed his notebook.
Outside, the London afternoon persisted. Inside the library, a developer had just learned that reading code you didn't write is less about cleverness than about patience — and that the map you build before you start walking is the thing that makes the rest of the journey possible.
Next episode: Margaret and Timothy turn to the language you don't know — how to approach a codebase written in an unfamiliar language, and what Claude Code can and cannot do when you're outside your expertise.
The Secret Life of Claude Code publishes every other day. If this series is useful to you, share it with a developer who needs to inherit someone else's code.
Aaron Rose is a software engineer and technology writer at tech-reader.blog. For explainer videos and podcasts, check out Tech-Reader YouTube channel.
Comments
Post a Comment