DEV Community: John Nickell

How to Understand a Codebase You Didn't Write

John Nickell — Tue, 07 Jul 2026 13:30:00 +0000

Think about how you find one word in a dictionary. You don't start at A and read every page. You open to the middle, decide which half your word's in, and throw the other half away. Then again, and again, until you're standing on top of it.

Now apply that to an unfamiliar codebase. That's the whole idea, and it turns "I have no clue where to start" into about four good questions.

The Advice Everyone Gives, and Why It's Wrong

"Read the whole codebase before you touch anything." I've given that advice and I've taken it, and I think it's wrong.

The intent behind it is fine. Nobody wants a new hire blundering into a critical path with zero context. But "read everything" isn't a method. It's a gesture. There are codebases I've worked in north of 200,000 lines. If I tried to read them front to back before touching anything, I'd still be reading.

What the advice produces instead is a specific kind of shallow familiarity. You've seen most of the files. You couldn't explain what any single module does. That's not understanding. That's having scrolled.

The Dictionary Trick

The method is the same bisection you'd use to find a word: ask what behavior you need to understand, then find where it enters the system. That's your first split. Everything off that path doesn't exist for now, not forever, just for now.

Most of the time the entry point takes minutes to find. HTTP endpoints have routes. Queue consumers have message types. Scheduled jobs have names. Once you have it, follow the behavior. Stop when you hit something you can't trace. Ask why that thing exists. Stop again. You're narrowing the codebase one bisection at a time until you land on the module that owns the thing you need.

The Seam

What you're narrowing toward is the seam: the boundary where one module's responsibility ends and another's begins. A well-built system has these. You can follow a behavior all the way through one module, come out the other side, and know exactly what that module's job is and where it stops.

This is not an argument for understanding less. Ignoring the parts of the system outside your seam isn't the same as shipping code you don't understand. It's how you get to the point where you can explain something. You own one thing completely and work outward from there. Every senior developer I've worked with does this instinctively. Nobody reads the whole repo on day one.

You can hold one thing deeply or ten things shallowly. The ten things feel like coverage. The one thing is what actually makes you useful.

The Scar

Here's the specific version, because none of this is theoretical. I got dropped into a project once with no documentation worth reading, and a git history where every commit message was "fix" or "update" or "final," then "final2." Ticket due Friday.

For the first few hours I did what most people do: opened the file tree, started reading. By hour three I had a dozen tabs open and understood nothing I hadn't understood when I started. I'd seen files. I hadn't learned anything.

The question that turned it around was almost embarrassingly obvious: what does this ticket actually touch? I found the entry point, an HTTP endpoint, and followed it. I stopped when I hit something I couldn't trace. I asked why it existed. I stopped again. Forty minutes later I had a solid model of one module and one clear flow through it. That was enough to start, and it was enough to finish. The rest of the codebase never revealed itself in those forty minutes. The part I needed did.

Four Questions, Portable

Write these on an index card:

Name the actual behavior, not the feature name or the ticket title. "A user cancels an order before it ships" is a behavior. "The cancellation flow" is a category.
Find where it enters the system: a handler, a consumer, a job. Almost always fast.
Follow what it changes. The state change tells you what the code actually owns.
Name what it depends on to run, for this behavior specifically. That's your context boundary. Everything outside it is outside for a reason, even if the reason is "not today."

The Tool That Shortens the Scar

Remember the forty minutes I spent finding one HTTP endpoint in a codebase whose git history read like a confession? There's a tool that would have cut that closer to five.

It's a Claude Code skill called Understand Anything. Install it once through the plugin marketplace, then from inside the project run /understand scoped to the folder you care about. Underneath, a multi-agent pipeline splits the work: tree-sitter handles the structural layer, Claude handles the semantic layer, and together they build a knowledge graph of every file, function, class, and dependency in that scope.

What you get is a dashboard. Click a node, see what it connects to. Read a plain-English summary of what a file is for. Ask a direct question, "what calls into this aggregate?", and it answers from the graph instead of re-reading the source. There's a guided tour too, ordered by dependency, so you learn a module in the order that makes sense instead of whatever order the file tree lists it in.

The piece I keep coming back to is the diff tool. Before you push, /understand-diff shows you what the graph says your change actually touches. That's a different question than what you think you're touching, and it's the kind of thing worth knowing before the PR goes out, not after.

It's free and MIT licensed. Find it here:

https://github.com/Egonex-AI/Understand-Anything

The Line to Protect

One thing I don't want to get lost in all of this: finding the right chunk and ignoring the rest is not the same as saying it's fine to ship code you don't understand. It's the opposite. The four questions are how you get to real understanding of one thing instead of a vague impression of everything.

You don't have to understand everything. You have to understand the right thing, and you have to understand it cold.

Watch the full episode for the visuals and the full walk-through of the method, plus the question I'm asking in the comments:

The Thinking Engineer — one channel, one bet: AI can write the code now, but somebody still has to understand it. That somebody is the job that isn't going away.

AI Won't Make You a Better Developer

John Nickell — Tue, 30 Jun 2026 13:35:00 +0000

The AI tool doesn't know what good looks like. It knows what common looks like. If you're thinking clearly about the problem, it'll help you build the right thing fast. If you're not... it'll help you build the wrong thing fast. Same tool. The difference is you.

That's the uncomfortable version. And it's the whole point of this post.

The Trap Is Comfortable

You sit down with Claude Code, describe what you want, and twenty minutes later there's a working feature on your screen. It feels incredible. It feels like you just got better at your job.

That feeling is the trap.

Something did get better in that moment. It just wasn't you. Your output got better. Your speed went through the roof. But speed is not skill, and output is not understanding. You moved faster across ground you didn't actually learn.

It's the difference between driving to the top of a mountain and climbing it. You get the same view in the photo. Only one of you can find the way back in the dark.

The Gap These Tools Hide

There's an idea from Ira Glass — he calls it the gap. When you start out, your taste is good before your skill is. You can tell that your own work isn't as good as the thing you admire, and that gap, that frustration, is what pulls you forward. You close it by doing the work, over and over, badly, until one day it isn't bad anymore.

Now look at what AI does to that picture. It doesn't close the gap. It hides it. It produces work at a level your taste can recognize as decent — but your hands could never have reached on their own. So the frustration that used to drive you disappears, and the daily reps that used to close the gap... you just stop doing them.

The output looks like a senior wrote it. You did not become a senior. And the thing that would have made you one is the exact thing you skipped.

The Teacher You Fired

Most of my education came from my own mistakes. Fifteen years in, almost everything I actually know, I know because I broke it first. I wrote the slow query that took the site down. I built the abstraction that everyone hated. I shipped the bug, traced it for two days, and finally understood the thing I thought I'd already understood.

The struggle wasn't in the way of the learning. The struggle was the learning.

When the AI removes the friction, it doesn't just save you time. It quietly removes the teacher. The hard part — the part where you sit there confused and have to build the model in your own head before the code will work — that part is doing something to you. Skip it every time, and yeah, you'll ship faster this quarter. But the version of you that could have handled the gnarly problem two years from now never gets built.

You optimized away your own apprenticeship.

Common Is Not Good

Back to that first line, because it's the load-bearing one.

The model knows what common looks like. Not what good looks like. Common is genuinely useful — the most common way to do a thing is usually fine, often even right, and getting "fine" in twenty seconds is a real gift. I use it every day.

But picture what the model actually is. It read a planet's worth of code and learned the average of it. When you ask it for something, it hands you back the middle of the distribution. The median answer.

Good code — the code you actually admire — almost never lives in the middle. It's a deviation. It's somebody who understood this specific domain well enough to do the uncommon thing on purpose, because the common thing was wrong here. The model can't make that call. It doesn't know your domain. It's pulling toward the average while the whole point of expertise is knowing exactly when to leave it.

If you can't tell common from good, you will ship common forever, and you'll think it's good, because it compiles and the tests pass and it looks like everything else you've ever seen.

You Are the Variable

So if the tool won't make you better, what will?

Two things. Same two things the good developers were already doing before any of this showed up.

The first is understanding over producing. Stop measuring yourself by how much you shipped and start measuring yourself by how much of it you could explain, out loud, to a skeptical room. Read the code the AI gives you like you're going to be quizzed on it — because someday you will be, probably at two in the morning. Trace why it made the choices it made. Use the tool to go fast on the things you already understand cold, and force yourself to do the hard part by hand on the things you're still learning. That's not nostalgia. That's just keeping the teacher employed.

The second is thinking clearly before you open the chat window. Domain-Driven Design, Clean Architecture, the SOLID principles — I think of all of it less as a set of rules and more as a way of getting honest about the problem before you let the machine run at it. Because an amplifier makes whatever you feed it louder, and it does not care whether what you fed it was any good. Feed it muddy thinking and you get a beautiful, fast, well-tested mess. Feed it a clean model of the problem, in the language the business actually uses, and the same tool is suddenly building exactly the right thing.

Same tool. You're the variable. You were always the variable.

Watch the full episode — visuals, the specific framework I use before starting any AI session, and the question I'm asking in the comments:

The Thinking Engineer — one channel, one bet: AI can write the code now, but somebody still has to understand it. That somebody is the job that isn't going away.

Nobody Understands Your AI Written Code

John Nickell — Tue, 23 Jun 2026 13:35:00 +0000

Picture Dave. Not a bad developer. Six years in, reasonably curious, catches most of the things that matter. Last Tuesday, Dave asked an AI to scaffold a feature. The AI wrote 340 lines in about four minutes. The code passed review. The tests passed. The feature shipped Friday.

The following Monday, the feature had a bug. Dave opened the file and stared at it for eleven minutes before typing a question back into the chat window.

That's the episode I made. Not about Dave specifically... Dave's a composite. But if you've been on a development team in the last two years, you've met Dave. Maybe you've been Dave.

The Cost Nobody's Tracking

There's a metric your team dashboard probably doesn't have: how long does it take a developer to answer a question about code they shipped?

Cycle time. PR count. Lines changed. Test coverage. Nobody's logging the eleven minutes. Nobody's logging it when "what does this do?" becomes "I'll ask the AI."

That's the hidden cost. Not the bugs. The bugs are findable. The cost is that finding them now requires a conversation with a prediction engine instead of a person who actually understands the system.

That compounds quietly. And then one day a senior developer leaves, and the AI doesn't remember what it meant when it wrote the thing, and neither does anyone else.

Where the Bottleneck Went

For most of software's history, the bottleneck was producing code. Senior developers were expensive, good ones were rare, and getting software out the door was genuinely hard.

That bottleneck is basically gone.

Claude Code can build a working feature in the time it takes you to make a pot of coffee. Junior developers can ship code that would have taken a senior developer two days. That's real, and it's not going away.

The new bottleneck is understanding what was produced. And the irony is that we've mostly just accepted it. The code ships, the feature works, and whether anyone on the team could reconstruct the reasoning behind it is a question we've stopped asking.

I think that's a problem that compounds.

Why DDD Isn't Overhead Anymore

I've spent years defending Domain-Driven Design against the "it's too much code" argument. That argument made some sense when every line was hand-written. It makes almost no sense now that the cost of writing a clean domain model is largely free.

DDD, Clean Architecture, Hexagonal Architecture. None of these were invented to make your codebase look impressive. They were invented to make complex systems understandable. To put the language of the business inside the code. To give future developers (and future you) a map.

When AI is writing the code, that map becomes more important, not less. The AI will write whatever you tell it to write. Give it a clean direction with clearly named concepts that match your domain, and you end up with code a person can actually read. Give it vague instructions inside a vague architecture, and you end up with 340 lines of passing tests that nobody can explain.

I've seen both outcomes. The difference isn't the AI. The difference is whether the developer understood the domain before writing the prompt.

The Five-Minute Habit

I cover this in the episode, and I won't give the whole thing away here, but the short version is this: before you prompt, write down what you're building and why. Not a ticket description, not a feature name. The actual intent. What domain concept is this touching? What is the expected behavior in business terms? What would make you confident this is correct?

Five minutes of that changes the code the AI produces. Significantly.

It also changes what happens when something breaks. Because the intent is written down, the debugging conversation is between you and the domain... not between you and an AI trying to guess what was meant.

That's staying in control of what you're building. In a year when the tooling can write faster than most of us can think, that habit is the job.

There's more in the episode. The hidden cost argument gets a fuller treatment there, and I talk through a specific exercise you can start on Monday morning.

I read every comment. Drop your war story below: the bug nobody could trace, the service nobody could explain. Those are worth hearing.

John Nickell — The Thinking Engineer