Loading...

Loading...

Comprehension Debt: If AI Wrote It, You Own It
Loading like and share buttons...
#comprehension-debt#ai-coding#code-review#pull-requests

Comprehension Debt: If AI Wrote It, You Own It

Vibki AI
Vibki AI
Nov 7•4 min read

Have you ever merged AI-written code you could not explain a week later? That gap is comprehension debt: the distance between the code your team ships and the code anyone understands. By the end you will know why the person who merges owns the code, and how to pay the debt down.

Did AI really make you faster, or just busier?

Let's see how that debt piles up. Friday, 16:40. An agent wrote a 440-line pull request (PR, a bundle of changes sent for review), the tests are green, and your finger hovers over Approve. Feels fast, right?

As of November 2026 one vendor's telemetry says AI-assisted teams write about 3.4x more lines, and the typical PR grows from 185 lines to 440. Releases got only about 4% faster.

Is comprehension debt just tech debt with a fancier name?

The time went into understanding. Comprehension debt is the gap between the code a team ships and the code anyone actually understands. Tech debt is a shortcut you chose and can point at. Comprehension debt arrives with green tests, and nobody notices it.

The same data shows churn (code rewritten or deleted soon after it lands) at 24.7% for AI-assisted work against 8.2% for the baseline. The Thoughtworks COO quoted by iTNews Asia, makes the same point with two terms. Generation velocity is how fast code appears, and delivery velocity is how fast understood, working software reaches users.

Where do you actually need to understand the code?

Earlier. At the plan. Before the agent types a line, you decide what changes, why this approach, and what breaks. That is the manifest, written before loading. The 440 lines are just the plan written out in code.

Reading the diff line by line afterwards is too late, because the decisions are already made. Our Friday PR had no plan, so nobody can say why it exists. If you want a refresher on planning first, start with The Plan is King.

So is code review pointless now?

No, but it is not where you learn the code. Review is where you explain. A teammate, the on-call engineer, or you next week asks "why this way?", and you answer from the plan. The inspector at the port does not rebuild the cargo, he asks "what is in this one?"

A second AI can find bugs. It cannot answer for you. The Thoughtworks COO, in the iTNews Asia interview quoted earlier, has a name for what happens next: cognitive surrender, accepting whatever the AI produces without checking that you understand it. Approving the Friday PR because the tests are green is exactly that.

Sounds easy? Try it: next time you approve, close the diff and say what the PR does out loud. If you cannot, you found your debt.

Does every pull request have to be small?

Prefer small, because small is easier to explain. A big PR is fine if you can explain it in two sentences: what it does, and what breaks it. For the Friday PR: "It adds retry logic to the billing webhook. It breaks if the provider sends the same event twice." If you can say that, merge. If you cannot, split it or go back to the plan.

Be pragmatic: triage by blast radius (how much breaks if this change is wrong). A throwaway script does not need a manifest, auth or payments code does. We covered how to build that plan in Vibki's planning workflow.

Conclusion

So who owns that Friday PR, the 440‑line one nobody can explain? You do, the moment you click merge. That also answers the question we started with: AI made typing faster, not shipping, because typing was never the slow part. Understanding is, and that work belongs in the plan, before the agent writes a line.

Before your next agent run, write the plan in three lines: what changes, why this way, what breaks it. That is how you pay comprehension debt down. Choose one PR this week and try it out!

Enjoyed this post?

Get the next one in your inbox. No spam, unsubscribe any time.

Comments

0 comments

Enter your comment. Maximum 2000 characters.

No comments yet. Be the first to share your thoughts!
Vibki logo wave icon
Vibki Surfing Bot
Vibki

Vibki is a developer blog where you will find tutorials on web development and AI integration. Each article is crafted with clear explanations, practical examples, and ready-to-use source code.

Talk to me
Copy email
LinkedIn
GitHub
Dev.to
Privacy Policy