Comprehension debt: what happens when nobody understands the code that ships

There is a number going around that should be read carefully rather than repeated: something close to 95% of organizations now allow machine-generated code into core production workloads, most of them formally.

Take the precise figure with the usual caution. The direction is not in doubt. Microsoft has said AI writes roughly 30% of its codebase, GitHub's own telemetry puts the average share across Copilot users near 46%, and Meta has signalled a 50% target. Whatever the exact percentage in your organization, it is not zero, and it went up this year without anyone deciding it should.

That is not the problem. The code is often good.

The problem is a specific liability that has been accumulating quietly, and it now has a name: comprehension debt, the cost incurred when an engineer accepts code they do not fully understand, ships it, and leaves the cognitive burden to every future engineer who has to touch it.

Why this is not just technical debt with a new label

Ordinary technical debt is a known shortcut. Somebody chose the quick path, usually knew it, and often left a comment saying so. It is legible. You can find it, estimate it and argue about whether to pay it down.

Comprehension debt is different in a way that matters operationally: it is invisible at the moment it is created, and it looks exactly like finished work.

The code passes review. The tests are green. The feature works. Nothing in your tooling distinguishes a function the author reasoned through from a function the author skimmed, found plausible, and approved. The two are byte-for-byte indistinguishable in the repository. The difference lives only in a person's head, and that person leaves the company in fourteen months.

A large-scale empirical study of AI-generated code in the wild found the pattern showing up in the artefacts themselves. Reporting on industry data has pull requests containing AI-assisted code carrying roughly 1.7 times more issues than human-written equivalents, with organizations seeing technical debt rise 30% to 41% within six months of broad adoption. Senior engineers report spending 20% to 35% more time in review.

Read that last one again, because it is the one that should worry a budget-holder. The productivity gain is real and it is landing on the person writing the code. The cost is real too, and it is landing on the most expensive person on the team.

The three places the bill arrives

Comprehension debt does not show up as a line item. It shows up as three operational symptoms that most organizations currently attribute to something else.

Onboarding gets slower. A new engineer's ramp-up time is a function of how much of the system somebody can explain to them. When large parts of the codebase were never fully understood by anyone still employed, onboarding stops being knowledge transfer and becomes archaeology. If your ramp time has quietly stretched over the last two years, this is a candidate explanation.

Debugging gets slower, specifically under pressure. This is the expensive one. An incident at 2am is the moment when the difference between code you understand and code you accepted becomes a cost measured in minutes of downtime. You cannot reason your way out of logic nobody can explain, and the model that wrote it is not on the incident call.

Regression rates rise. Changes to opaque code break things that were not obviously connected, because the dependencies were never in anyone's mental model. The team experiences this as "the codebase has gotten fragile," which is accurate but misdiagnosed.

What we do about it

We use these tools. Refusing them would be a strange position for a firm whose entire argument is that the cost of building software collapsed. The question is not whether to use them but what has to remain true regardless.

Nothing merges that the author cannot explain. Not "has read" but can explain: why this approach, what happens at the edges, what breaks if the input is malformed. If the answer is "the model suggested it and the tests pass," it is not ready, however correct it turns out to be. This is one rule and it does most of the work.

Review effort scales with blast radius, not with diff size. A 600-line change to an internal report can be reviewed briskly. A 40-line change to the code that calculates a settlement amount gets read character by character, because what a wrong answer costs is the only variable that has ever mattered. AI shifts where the lines come from; it does not change this calculus at all.

Generated code gets fewer clever abstractions, not more. Models are good at producing sophisticated, general solutions. Sophisticated general solutions are exactly what is hardest to hold in your head a year later. We push generated code toward being boring and explicit, because the maintenance property we want is legibility, not elegance.

The unglamorous 60% is still ours. Error paths, the malformed file, the offline user, the exception nobody documented. Models are trained on code that mostly handles the happy path, because that is most of the code in the world. The parts that decide whether a system survives a bad Tuesday are the parts where review has to be hardest.

The honest counter-argument

Somebody will point out that engineers have shipped code they did not fully understand since long before models existed. Copied from Stack Overflow, inherited from a contractor, pulled in as a dependency with 400 transitive packages.

That is completely true, and it is the reason this is worth taking seriously rather than dismissing. We already know what that failure mode looks like at small volume. It looks like the system that one person understands, which is the exact condition most of our clients hire us to escape.

What changed is throughput. The mechanism is old; the rate is new. A team can now generate more code in a quarter than it can collectively comprehend in a year, and nothing in the workflow makes that visible until the incident.

The test we would apply

If you want a single diagnostic, it is not a metric and you cannot buy a dashboard for it.

Pick a file that shipped in the last three months and matters, something in the billing path, the permissions model, the part that touches money or records. Ask the engineer who merged it to walk you through what happens when the input is wrong.

If that is a comfortable conversation, your process is working, and you should carry on using every tool available.

If it is not, you have found the debt. It is worth knowing the size of it before the night you need to know.

Our position has not changed since we started: software is only finished when it survives contact with real work, and somebody has to still be accountable for it afterwards. That is how we build, and it is why we stay on after go-live rather than handing over a repository and a good luck message.