Cognitive Debt: The Maintainability Bill for AI Code

Six months after the feature shipped, a customer hit an edge case and the team opened the file to fix it. The code was clean, well-formatted, even commented. And nobody in the room could say with confidence what it actually did. It had been generated in an afternoon, skimmed, approved because the tests were green, and merged. Now it was load-bearing — and the only thing that had ever truly understood it was a model that had since moved on to a newer version of itself. The bug was small. Fixing it safely took a week, because first the team had to learn the code they supposedly already owned.

What cognitive debt is

Cognitive debt — sometimes called comprehension debt — is the accumulating gap between the code running in your system and the code your team actually understands. Classic technical debt is code that is hard to change because it was written badly or in a hurry. Cognitive debt is different: the code may be perfectly well-structured, but no human has internalised why it works, what it assumes, or what will break if it changes. AI makes this debt easy to take on and hard to notice, because generated code arrives looking finished — and looking finished is exactly what stops anyone from doing the work of understanding it.

The early evidence points one way. Analyses of large code corpora as AI assistance spread show duplicated code blocks rising sharply while the proportion of changes that refactor — the housekeeping that keeps a codebase coherent — falls. Thoughtworks named the underlying risk on its 2026 Technology Radar and prescribed, of all things, a return to engineering fundamentals. Industry surveys report a majority of organisations hitting production issues traceable to AI-generated code they had not fully understood. Read together, the signal is not that AI writes bad code; it often writes good code. It is that volume is rising while comprehension is falling, and the distance between the two is the debt.

Treat the precise figures with the usual caution — much of this is recent, some is vendor data, and “duplicated code” is an imperfect proxy for understanding. But the direction is corroborated across independent sources, and it matches what teams report once the first flush of speed wears off.

Why it compounds silently

Three properties make cognitive debt worse than the technical debt we are used to.

• It is invisible at merge. A linter flags style; no tool flags “nobody understands this”. The debt is taken on precisely when everything looks green.
• It compounds. Each generated change a team does not understand makes the next one harder to reason about, because the context you would need is itself unowned. Comprehension is a stock, and it is being drawn down.
• It moves the cost in time. The bill does not arrive this sprint. It arrives the quarter you must change the system under pressure and find that the understanding required to do it safely no longer exists.

This is the same shape as the AI productivity paradox: the speed is real and local, and the cost reappears later, downstream, on someone else’s desk. Cognitive debt is one of the specific forms that deferred cost takes.

The question that exposes cognitive debt is brutally simple: if the model vanished tomorrow, could your team still change this code safely? When the honest answer is no, you do not have a productivity gain — you have a liability the dashboard has not noticed yet.

How to keep comprehension ahead of volume

You cannot generate your way out of cognitive debt; the only currency that pays it down is human understanding, so the controls are about protecting that. None of them is exotic.

• Keep diffs small enough to understand: a change a reviewer cannot hold in their head will not be understood, only approved.
• Make comprehension part of review, not just correctness: the reviewer’s job is to confirm a human understands the change, not only that the tests pass. “Could you maintain this without the AI?” is a fair gate.
• Write tests that document intent: tests are the executable explanation of what the code is for — the one artefact that survives when the author and the model have both moved on.
• Refactor deliberately: schedule the housekeeping AI tends to skip, because a coherent codebase is a comprehensible one.
• Put “understood by a named person” in the definition of done: ownership of understanding, not just of the merge.

These are old disciplines — small changes, real review, tests as documentation, deliberate refactoring. AI did not make them obsolete; it made them load-bearing. The fundamentals are the control precisely because the model removed the friction that used to enforce them.

The principle underneath

Generated code is not free; it is borrowed against future understanding. The speed is real, and so is the loan. The teams that stay fast over years are not the ones that generate the most — they are the ones whose comprehension keeps pace with their output, so the system stays changeable by the people accountable for it. Ship code your team understands, or accept that you are renting a system you no longer own.