Understanding Your Whole Codebase Isn't the Point (And With AI Agents, It Can't Be)

I want to make a case for something that sounds uncomfortable at first: if you fully understand every line of code in a project, that project probably isn't very important. The bigger and more consequential the system, the less likely it is that any single person, you included, actually understands all of it. Nobody understands every line of an operating system, a major platform, or a foundational piece of infrastructure like a database engine. We just like to pretend otherwise.

The myth of the engineer who knows everything

Our industry has a favorite image of the "great engineer": someone who can point to exactly where everything lives in the codebase, at all times. In practice, I don't think that person exists, not for anything large enough to matter. What experienced engineers actually have isn't total recall. It's a strong intuition for where things should be, built from a higher-level sense of how good software gets structured. That intuition is what makes a codebase navigable even for people who didn't write most of it. A good codebase isn't one where everyone already knows where everything is. It's one where finding the right place for something doesn't take long, even if you're new.

Code is a byproduct, not the product

There's a real idea behind this, from a 1985 paper by Peter Naur called "Programming as Theory Building." Naur's argument is that the code itself is mostly a byproduct. The actual thing a team builds while working on a program is a shared theory of it: an intuitive sense of why it works the way it does, which can never be fully captured in the code or the docs. That's why losing the code is recoverable (you can rewrite it), but losing the people who understood it is a much bigger loss. A team with zero institutional memory can stare at working code and still struggle to safely change it.

I think that's true, but I'd push back a little on the idea that a full rewrite is the answer once the theory is gone. In practice, successful rewrites almost never start from a blank page. They start by carving the existing system into small pieces and replacing one piece at a time, because a codebase with real users has accumulated years of odd edge cases, quirks, and specific fixes for specific problems that no one will remember to reproduce from scratch. You can't safely change a system you don't understand, and you can't safely discard one either.

Partial understanding is a trade-off, not a failure

Here's the part I find genuinely freeing: in any sufficiently large system, everyone is operating on a theory that's at least partly wrong. That's not a sign of a bad engineer. It's just what happens once a codebase is too big for any one head to hold. A long list of completely normal things chip away at anyone's full understanding of a system: other people contributing code, compliance and accessibility requirements, colleagues changing teams, routine dependency upgrades, adding a new integration. None of those are bad. They're just costs you pay for building something real, and they mean your personal theory of the system will always be incomplete.

TypeScript is a small, concrete example of choosing this trade-off on purpose. A type checker takes over a category of thing you'd otherwise have to hold in your head — is this the right type, did I pass the right shape of data — and once it's handling that for you, your understanding of the raw mechanics goes down a notch. But your ability to make correct changes quickly goes up. That's a good trade. The goal isn't maximum understanding for its own sake. It's understanding enough of the right things to make good decisions reliably.

What changes with AI agents

This is where it gets interesting for how I actually work now. An AI coding agent doesn't carry institutional memory between sessions. Every new conversation starts with effectively zero context about the codebase's history, its quirks, or the reasoning behind past decisions. It's the equivalent of onboarding a brand-new, very capable engineer from scratch, every single time you open a new thread.

That sounds like a problem, and it can be. But it's also forced a useful shift in how I think about my own understanding. Instead of trying to hold the whole system in my head, what matters more now is knowing how to give a capable-but-context-free agent enough structure to act well without that history. That means investing in the things that transfer knowledge without requiring a human to remember it: clear documentation of decisions and their reasoning, consistent patterns the agent can infer from, and instructions files that carry the parts of the "theory" that would otherwise live only in someone's head. I've worked on projects where I genuinely could not tell you the implementation details, but I understand the shape of the system well enough to steer an agent toward the right fix when something breaks. That's a different kind of competence than knowing every line, but it's a real one.

Where I land

Full understanding was never really available for anything that mattered. We just told ourselves a comforting story that it was. What actually matters is having a good-enough theory of the system to make sound decisions, knowing which parts you can safely be fuzzy on, and, increasingly, knowing how to hand that partial theory to something with no memory of yesterday and still get good results. That's not a lesser kind of engineering. It might be the more honest kind.