Path towards Comprehension Debt

What exciting times we do live in. In the past it was always the human developer who was the bottleneck. Writing code to pass a certain gate (e.g. test coverage plus acceptance criteria of what you wanted to implement) and have someone else review the code before it got merge into the upstream branch.

We always thrived to not start with the coding but instead start specing out what we wanted to achieve in a proposal (german Lastenheft), laying out what the feature aims to achieve without describing the implementation in detail and create a design (german Pflichtenheft) to describe how it’s going to be implemented.
But who was really doing that? Going through the discussion of dozens of stakeholders who might not even agree of what needs to be done.

It was a labourious ideal that we skipped by writing a prototype to proof the point (and buy-in by higher echolons) and have security, observability, maintainablilty being bolted on later.

All of this was (somewhat) managable through bolting on and incremental improvements - maybe even a fresh start after the prototype was greenlit.
Writing code took some time and once it was about to be merged into upstream, senior team members reviewed the code, proposed changes, and finally merged what was written.
These were (hopefully) concious decisions, the proposing software engineer knew his code after all.

Technical Debt

In case the review found something that is a risk or missing feature (or otherwise sub-optimal) we piled it on the stack of technical debt (Wikipedia).

• Missing algorithm for encryption? Put it in the technical debt!
• Quick’n’dirty implementation of a database query? We’ll improve it later!
• Update to the latest version of a library? On the debt stack!

A lot was written about it, so I do not need to elaborate. I really like this blog post by IBM about the topic. Here’s the first paragraph:

Technical debt refers to the future costs associated with relying on shortcuts or suboptimal decisions made during software development. Also called code debt or design debt, these compromises are primarily due to quick fixes, poor documentation and reliance on outdated code. Over time, this debt must be addressed, requiring additional effort. This “repayment” typically involves refactoring, debugging and ongoing code maintenance.

At the end of the day we always told ourselves we’ll get to it when the pace slowed down and we have time to address the debt from the past. Of course we never did.

Code Genration (on steriods)

But that was then and times have changed. Developing the code is not the bottleneck anymore.
Even tho it’s not yet at neck breaking speed, it is already incredibly fast. Code is generated in a couple of minutes with sequential generation (token by token), currently at a rate of dozens (or if you are lucky hundreds) of tokens per second.

But that’s going to change, similar to how stable difussion images puke a blob of pixel into existance and optimize them organically - diffusion text generation might do the same to text.
(Alternatively we might get token-by-token generation so fast that it does not matter how it consitutes itself.)

Here’s an example of how Mercury2 generates text in comparison to a normal transformer model (Source: levelup.gitconnected.com):

Anyhow, what I am saying is that the current trend of “As an AI infused software engineer you need to multi-task b/c you need to overlap multiple objectives to keep yourself busy” is going to be overtaken by reality.

Once the code creation is almost instant you are going to push the coding task (more like herding cats) through in one sitting without context switching.

Comprehension Debt

And that leads to the title of the blog post. We humans should not assume (at least I can’t) we just need to watch youtube while coding happens and hit enter at the end. Humans need to understand what is going on - and comprehend what the AI just put together.

I came across the article Comprehension Debt The Hidden Cost of AI-Generated Code at oreilly.com which resonnated with me.

It describes how we are going to struggle to keep up with code generation. I suppose even a non-technical person is now able to use an AI agent (Claude Code, OpenCode, …), point to a code base and ask ‘please add this feautre I think is missing’. And at the end you’ll have code written - if the user uses the right boilderplate agent it might even add a spec with a proposal, design and specs - all tests being green and the commit message:

Why not merge it?

And how are you going to argue against it? Even better (or worse) the new phrase you are going to hear more about is prompt & paste (iteration of copy & paste).
You do not need to find the code snippet that serves your purpose, you’ll ask the AI agent to generate it “from scratch”.

And that’s where we are going to end up in: wall of comprehension debt. The code looks good, the tests are green, and the spec is well writen and followed by the code submitted.

But that’s what AI is especially good in: mimic human prose and make it look good. I am not saying that it is going to bad per se. But it might just be a feature that was only urged for by one human being on the planet. Are you going to reject it?

Thus, we need to make sure we stay at the helm of this software development ship and stear it. At least for bigger projects.

Please make sure to have folks discuss architecture, lift up junior software engineers by giving them some room to play around and be non-perfect.
We need humans who are able to comprehend code on a project scope - and for that we need to train them (same as ourself relearn some 80’s software project manager stuff we always smiled at) to keep being the human in the loop.

We’ll see

As said at the very top: What exciting times we do live in.

I have seen weird shit in my career and I am happy to tackle this new paradigm shift as well. We argued about InfiniBand, DevOps and containers (to just score a couple of hits on the BullShitBingo card) for a decade and had a lot of (fun) debates about technology.

In the coming years we need to cope with this as well - and we will! If everyone can think up a spec and have an agent vibe code the solution I reckon that is a good think for humanity. We just need to make sure we distinguish between ‘proof-of-concept’ prototypes for a use-case (even tho they are going to look great) and something that is led by an architect who is staying on top of the project. That’s going to be very demanding b/c who is going to argue with the (very) confident AI agent reasoning like a ivy-league attorney.

We’ll see - looking forward to it.