We got called into a production incident last month. Mid-sized fintech, solid engineering team, series C, moving fast. They’d shipped a payments reconciliation service three weeks earlier. It worked. Tests passed. Transactions were flowing. Then an edge case in currency conversion started silently misallocating fractional cents across high-volume accounts, and by the time anyone noticed, the discrepancy was six figures.
Standard incident response. Pull up the code. Walk through the logic. Figure out what went wrong.
Nobody could.
The service had been built almost entirely by an AI coding agent. The engineer who’d prompted it had moved on to the next feature. The engineer on call hadn’t written it, hadn’t reviewed it beyond a quick scan, and couldn’t trace the reconciliation logic end to end. The code was clean. Well-structured. Perfectly idiomatic. And completely opaque to every human in the room.
They ended up asking the same AI tool to diagnose the issue. It suggested three possible causes, two of which were wrong. The third was in the right neighborhood but missed the actual root cause by a layer of abstraction. A senior engineer who’d been pulled off another project finally traced it manually over the next four hours by reading the code line by line, the way we used to do things.
This story isn’t unusual anymore. We’re seeing a version of it in nearly every engagement.
The comprehension gap
Here’s what changed, and it changed fast.
Eighteen months ago, an engineer writing code understood that code because they wrote it. The act of authorship was the act of comprehension. You understood the reconciliation logic because your fingers typed the reconciliation logic. You knew the edge cases because you’d thought through them while writing the conditionals that handled them.
That coupling is gone.
Today, an engineer describes what they want, an AI generates it, they glance at the output, confirm it passes tests, and ship. The comprehension step — the part where a human actually understands the logic, the failure modes, the edge cases, the implicit assumptions — is now optional. And optional things, under deadline pressure, get skipped. Not maliciously. Not even consciously, most of the time. It just happens, because the process no longer requires comprehension to produce working software.
The result is codebases where the gap between “what we shipped” and “what we understand” is widening every sprint. Not because the code is bad. Often it’s better than what the team would have written manually. It’s just that nobody can explain it under pressure, and “under pressure” is the only time that explanation matters.
Why the usual fixes don’t work
The natural response is to reach for tooling. More observability. Better agent guardrails. Tighter CI pipelines. These are all fine things to have. They also don’t solve this problem.
Observability tells you that the reconciliation service is producing incorrect outputs. It doesn’t tell you why the logic breaks on certain currency pairs, because that requires understanding the logic, which is the thing you don’t have. You’re instrumenting the black box. The box is still black.
Agent guardrails and pipeline hardening are the same story. You’re adding automated checks around code that no human has internalized. When the checks catch something, great. When they don’t — and they won’t catch everything, because no test suite is exhaustive — you’re back to a human trying to understand code they didn’t write and never read carefully.
The most seductive version of this is the idea that the AI can just fix its own code. The model wrote it, the model understands it, the model can debug it. This sounds efficient. In practice, it means you’re asking a system with known failure modes under pressure to diagnose problems in its own output under pressure. We wrote about this recently — models under internal pressure take shortcuts. Asking a model to fix its own broken code in a production incident is asking it to do exactly the kind of high-stakes, constrained task where those shortcuts are most likely to occur.
None of this means you shouldn’t have observability, guardrails, or AI-assisted debugging. You should. But they’re compensating controls, not solutions. The solution is comprehension, and comprehension is a human activity that requires organizational commitment.
What we’re actually seeing work
The teams that aren’t blowing up aren’t the ones with the fanciest tooling. They’re the ones that made a deliberate decision to protect comprehension as a first-class engineering value, even when everything else is pushing toward pure speed.
Three patterns keep showing up.
They spec before they generate. Not extensive documentation. Not waterfall-era requirements binders. Just a clear written statement of what they’re building, why, what it depends on, how it should fail, and what success looks like. Usually a page or less. The discipline isn’t in the length; it’s in the act of forcing a human to think through the problem before an AI starts solving it.
This has a secondary benefit that most teams discover accidentally: the spec becomes the eval. If you’ve written down what the code should do in clear enough terms, you’ve also written the acceptance criteria that the generated code needs to satisfy. You can hand the spec back to the AI as a verification prompt. You can hand it to a reviewer as a comprehension guide. The spec is the cheapest, highest-leverage artifact in your entire development process, and most teams have stopped writing them because AI made it feel unnecessary.
They embed context in the code, not in people’s heads. The teams that manage their comprehension gap well treat their codebases as things that need to be legible to the next reader — whether that reader is a human or an AI tool. Modules describe what they do and what they depend on. Interfaces carry behavioral contracts, not just type signatures. Failure modes are documented where they’re handled, not in a wiki that nobody updates.
This is context engineering, and it’s the difference between a codebase that can be understood by reading it and a codebase that can only be understood by the three people who were there when it was built. When two of those three people leave, the codebase becomes unownable. We see this every quarter. It’s always the same conversation: “We need help, we lost the people who understood the system.” If the understanding had been in the system instead of in the people, that conversation wouldn’t be happening.
They review for comprehension, not just correctness. Code review in a lot of shops has become a rubber stamp. PR comes in, CI is green, someone clicks approve. This was already a problem before AI-generated code. Now it’s a liability.
The teams doing this well have structured their review process to surface comprehension questions, not just correctness checks. Why this approach instead of the simpler one? What happens when this dependency is unavailable? How does this interact with the service upstream? These are the questions a good senior engineer asks instinctively. The problem is that senior engineers are reviewing more code than ever, generated faster than ever, and the instinctive questions don’t scale.
Some teams are using AI to generate those questions — a comprehension layer on top of the generated code that flags architectural decisions, unusual patterns, and implicit assumptions for human review. It’s not perfect. It is dramatically better than the alternative, which is hoping someone notices the problem in a wall of green checkmarks.
This is a leadership problem
If you’re running an engineering org right now, the question you need to be asking isn’t about your CI pipeline or your agent framework. Those are engineering problems with engineering solutions. The question is whether your organization has the discipline to maintain comprehension at the speed you’re shipping.
That’s a leadership problem. It means deciding that understanding the code is not optional, even when skipping it would be faster. It means staffing for comprehension, not just velocity. It means recognizing that every engineer you lay off is not just a reduction in output capacity — it’s a reduction in the organizational ability to understand and own what’s already been shipped.
The teams that are going to thrive in AI-assisted development aren’t the ones generating the most code. They’re the ones that can explain their code under oath, in a board meeting, during a SOC 2 audit, or at 3 AM when production is on fire. Speed is a prerequisite. Comprehension is the differentiator.
We’re pro-speed. We build fast. We use AI tools extensively. And we also believe that shipping code you don’t understand is just generating technical debt with a longer fuse. The explosion is the same. You just don’t hear it coming.
If your team is shipping faster than it can explain, we can help you close that gap without slowing down. That’s actually the whole point. Start a conversation.