Insights / Engineering practice
Engineering practice
What does it actually mean to understand a codebase?
Nobody remembers every line of code — not even code they wrote themselves a couple of months ago. And yet we treat "understanding the codebase" as a prerequisite, almost a gate before meaningful work can begin. I've been questioning that more seriously lately.
Most codebases are inherited anyway. But when you look closely, what engineers actually have is something much looser. They know which modules are fragile. They know where things tend to break. They have a sense for how far a change might ripple. They remember the last time a particular service caused a prod disruption.
The reframe
That's not understanding. That's navigational familiarity.
And we've been using it as a proxy for something harder to name.
The thing we actually care about is this — can you predict what happens when you make a change? Which parts of the system will be affected. Which assumptions you might be violating. Whether something fails loudly or quietly degrades.
That's the real bar. And it's different from knowing your way around.
Seen through that lens, AI already clears the first hurdle comfortably. An agent with access to code history, tests, PR comments, and architecture docs has better navigational coverage than most engineers working in a large inherited system. Where it remains uneven is prediction — particularly around implicit invariants and production edge cases that never made it into tests or documentation.
But if that gap closes — and I think it will — then "the developer must understand the code" stops being a safety principle. It was always a proxy to begin with.
This challenges something I've advocated for. In PBVI — Plan, Build, Verify, Integrate, the core loop behind how we deliver — we ask developers to predict outcomes before verifying AI-generated code, precisely to manufacture that predictive capability before anything gets touched. The assumption underneath that was: human understanding is the gate.
The implication
Maybe the more honest framing is — predictability is the gate.
Human understanding was just the best way we had to get there.
If AI can navigate and increasingly predict, what exactly are we asking humans to verify?
I don't have a complete answer yet. But I think the question itself changes how we should be designing human oversight in AI-assisted development.
Next step
Curious how we build with AI in the loop?
The predict-before-verify discipline this post describes is part of the framework behind every engagement we deliver.