Technical debt in the AI era: the problem two years from now

Technical debt in AI-assisted work can surface when you have to change code that works but that the team can't explain. “Two years from now” is a way of looking at future maintenance, not a deadline predicted by a study. The question I care about is: who will be able to reconstruct the reasons behind the choices?

Generating code and understanding it are two different activities#

An assistant can propose a change, and the tests can pass. Before release, one question remains: have we checked that the behavior is the one we asked for, and that the code is sustainable in our project? A formal review doesn't answer that on its own.

I wouldn't pin this on one category of developers. It's a process risk: if we accept changes faster than we can evaluate them, understanding can fall behind. You don't need to assume the same productivity gain for everyone to recognize the problem.

Cognitive debt: a debt that doesn't show up in tests#

Here I use “comprehension debt” to describe code that the team struggles to explain and change. It's a way of reading the problem, not a standard metric or a finding attributed to research I haven't cited. It can come alongside technical debt even when the feature seems correct.

The code is there, it's in production, it runs. But if the person who did the prompt-and-merge leaves tomorrow, that piece becomes a kind of black box inside our own house. It works until it doesn't.

A maintenance scenario to use as a test#

Imagine a colleague who joins a project and asks why a function updates the data in a particular order. This is a hypothetical scenario, not an account of an onboarding that actually happened.

The code is readable and the tests pass, but it isn't clear which constraint led to that sequence. Before changing it, the team has to reconstruct the behavior, the alternatives and the consequences. This is where missing context turns into real work.

I would use this test during review: can someone explain what happens, why, and what could break? If nobody can answer, you may need a check, a design note or a more meaningful test. Not necessarily a refactor.

A practice to try: read the diff without generating anything else#

One simple proposal is to set aside a session for reading the diff before asking the assistant for more changes. The goal is to keep understanding and production apart: inputs, effects, errors, dependencies and the reasons behind the solution.

How long it takes depends on the change. I wouldn't turn it into a timed ritual: a small fix and an architecture change need different kinds of attention. What matters is that the review addresses the real risks.

A changing craft: from writers to reviewers#

When we work with assistants, part of the job shifts toward evaluating and verifying their proposals. That doesn't mean design and writing disappear: the responsibility to understand the system we're changing stays with us.

Automated review has limits too: GitHub points out missed issues and false positives, and recommends that people review Copilot's comments. That's a reason to use AI review as support, not as conclusive proof. Source: limitations of GitHub Copilot agents.

In my work I use AI to build products and to think them through. I don't pretend there's a definitive formula: what interests me is which practices make code easier to change, including for whoever comes after.

The skill that (maybe) will matter most: reading slowly#

I think the ability to read carefully becomes even more important when generating a proposal is easy. This is my personal view: the value lies in spotting wrong assumptions, hidden constraints and consequences before accepting the change.

• Read the diff against the behavior you asked for.
• Explain to a colleague why the solution respects the constraints.
• Document the reasons that aren't obvious, without assuming the AI will reconstruct them.
• Use the questions of people joining the project to find the missing context.

What to do in your team today#

These are practical starting points, to adapt to your team and to how critical the changes are:

1. Identify the important areas that nobody can explain with confidence.
2. Review changes before release and verify the critical behaviors.
3. Document constraints and reasons wherever they can't be worked out from the code.
4. Use maintenance and onboarding questions to improve tests and documentation.

An open question#

Next to the amount of code, I would put a question about maintenance: how hard is it to understand and change what we've accepted? It isn't an argument against AI. It's a way of judging the work beyond the first version that seems to work.

In your team, who can explain the most important parts of the system? If that person weren't available, where would you find the reasons behind the choices? It's a useful question to ask today, without waiting for a problem to show up.

If you have a concrete experience with this - an onboarding that went badly, a reading practice that works for you, a maintenance disaster - write to me on LinkedIn. I'm collecting real cases, not opinions.

Sources#

• Limitations and responsible use of agents, GitHub Copilot