Addy Osmani dropped a piece last week that's been making the rounds: "Comprehension Debt — The Hidden Cost of AI-Generated Code." His thesis is sharp. Teams are shipping AI-generated code faster than anyone can understand it. Tests pass, PRs look clean, and nobody notices the growing gap between what's been deployed and what any human actually comprehends. When something breaks at 3am, that gap becomes the bill.
He's right. And he's not seeing the whole picture.
Osmani diagnosed one symptom of a larger condition. Comprehension debt — the gap between shipped code and understood code — is real, and it matters. But it's one line item on a ledger that most engineering organizations haven't even opened yet. If you're a CTO or VP of Engineering adopting AI-assisted development, comprehension debt is the problem you can see. The ones that will actually sink you are the ones you can't.
The AI Debt Paradox
There's a seductive argument circulating in engineering circles right now: AI makes rewriting cheap, so tech debt doesn't matter anymore. Why maintain a crumbling monolith when you can regenerate services in an afternoon?
It's about 40% right, which makes it dangerous.
Yes, the cost curve of rewriting code has collapsed. For bounded, well-specified modules, AI absolutely turns "rewrite" from a quarter-long initiative into a day's work. The classic excuse — "we can't touch that, it'll take months" — is dying. That's real progress.
But here's the paradox: every time you "start from scratch," you throw away embedded knowledge about why decisions were made. The 47 edge cases handled one by one over 18 months. The compliance requirement someone baked in after an audit. The OAuth flow three partners hardcoded against. AI can regenerate the code layer fast. It cannot regenerate the institutional context that made that code correct.
Tech debt didn't disappear. It shape-shifted. And the new forms are harder to detect, harder to measure, and harder to pay down.
Three Debts, Not One
Osmani gave us a name for the first one. Here are the other two.
1. Comprehension Debt (Osmani's Contribution)
This is the gap between the code your team ships and the code your team understands. Osmani nailed the mechanics: AI-generated code passes review because it looks right, engineers approve PRs they haven't fully internalized, and the organizational assumption that "reviewed = understood" quietly breaks down.
The insight is correct. But the prescription — slow down, review more carefully, quiz your engineers — is a cultural intervention. It treats comprehension debt as a discipline problem. For Google-scale teams with senior engineers and strong review culture, that might work. For the other 95% of engineering organizations? You need more than discipline. You need infrastructure.
2. Context Debt
This is the one nobody's naming clearly, and it's the most dangerous.
Context debt is the accumulated loss of institutional knowledge about why systems are built the way they are. It's not about whether engineers understand the code in front of them — it's about whether anyone understands the decisions, constraints, trade-offs, and edge cases that shaped it.
Consider what lives in a mature codebase beyond the code itself:
-
Architectural rationale. Why this service exists as its own deployment rather than a module in the monolith. Why the database schema looks the way it does. Why that particular API contract was chosen over three alternatives that were debated for weeks.
-
Boundary knowledge. Which downstream consumers depend on specific response shapes. Which partner integrations are fragile. Which compliance requirements are baked into the data flow and why.
-
Failure memory. The incident that revealed a race condition nobody anticipated. The scaling problem that drove the caching strategy. The security audit finding that explains the seemingly redundant validation layer.
None of this lives in the code. Very little of it lives in documentation. Most of it lives in the heads of engineers who were there when the decisions were made. When AI regenerates a service from scratch, it produces code that compiles, passes tests, and handles the happy path. What it cannot produce is the scar tissue — the hard-won understanding of what goes wrong and why.
Context debt accumulates every time a team rewrites without capturing context first. Every time an AI-generated solution replaces a human-authored one without preserving the reasoning behind the original. Every time an engineer leaves and their knowledge of why things are the way they are walks out with them.
This isn't new — context loss has always been a risk in software organizations. What's new is the velocity at which AI-assisted development can destroy context. When rewriting is cheap, the incentive to understand before replacing drops to zero.
3. Integration Debt
The third form is architectural. Integration debt is the growing inconsistency between AI-generated components that were each built in isolation without awareness of the broader system.
AI coding assistants operate within a context window. They see the file you're working on, maybe some adjacent files, maybe a system prompt describing your stack. What they don't see is the full topology of your system — every service, every contract, every shared assumption that holds your architecture together.
When three different engineers use AI to independently build three services that interact, each service might be internally excellent. Clean code, good patterns, thorough tests. But the interfaces between them — data formats, error handling conventions, retry semantics, authentication flows — will diverge unless someone is deliberately enforcing coherence.
The numbers back this up. CodeRabbit's 2026 analysis found teams merged 98% more PRs that were 154% larger year-over-year, while 61% of developers reported that AI produces code that "looks correct but is unreliable." The generation pressure is real. The verification pressure is downstream — and growing.
Integration debt compounds quietly. It shows up as unexpected failures during deployment. As subtle data inconsistencies between services. As "it works on my machine" problems that are actually contract mismatches between components that were never designed to work together, despite technically needing to.
The faster you generate components, the faster integration debt accumulates. And unlike code quality — which AI can actually help improve — integration coherence requires exactly the kind of big-picture architectural thinking that AI tools are worst at.
The Composition Shift
Here's why this matters strategically, not just technically.
For two decades, "tech debt" mostly meant code-level debt: poor abstractions, missing tests, duplicated logic, outdated dependencies. That's the debt AI is genuinely good at paying down. Refactoring, test generation, dependency updates, code modernization — these are tasks where AI excels. If your tech debt balance sheet was entirely code-level debt, the "AI makes debt irrelevant" crowd would be right.
But in any system of real complexity, code-level debt was always just the visible portion. The deeper liabilities — context, comprehension, integration — were always there. They were just overshadowed by the sheer volume of code-level problems.
AI didn't eliminate tech debt. It paid down the most visible kind, revealing the structural kinds that were hiding underneath. The balance sheet didn't shrink. The composition changed. And most organizations are still using the old chart of accounts.
The 2024 DORA report hints at this shift: despite widespread AI adoption, throughput dipped 1.5% and stability dropped 7.2% across 39,000 respondents. Teams are generating more code and shipping it less reliably. The metrics that matter — lead time, change failure rate, recovery time — aren't improving with velocity alone.
Context as Infrastructure, Not Culture
This is where I part ways with the prevailing conversation.
Osmani and others are framing these new debts as cultural and organizational challenges. Slow down. Review more carefully. Keep humans in the loop. These aren't wrong, but they're incomplete — and for many teams, impractical. You can't tell a startup burning runway to slow down their AI-assisted velocity for the sake of comprehension hygiene. You can't tell a team of five to institute Google-style code review rituals.
What you can do is treat context as infrastructure.
I've been arguing for a while now that context management is the real skill gap in AI-assisted development — that getting value from AI tools is less about prompt engineering and more about maintaining rich, current, accessible context that those tools can leverage. (I wrote about this in "This Above All: To Thine Own Context Be True" earlier this year.)
The same principle applies to the debt problem, but at organizational scale. Context debt isn't an inevitable consequence of AI adoption. It's an infrastructure failure — a failure to build systems that capture, maintain, and surface the institutional knowledge that makes code comprehensible and architecturally coherent.
What does context infrastructure look like in practice?
Living architectural decision records. Not dusty wiki pages nobody updates, but actively maintained documents that live alongside the code and get updated as part of the development workflow. Michael Nygard formalized the ADR pattern back in 2011 — Title, Status, Context, Decision, Consequences. The format is fifteen years old. What's changed is that AI makes the cost of not having ADRs catastrophically higher. When AI generates a new implementation, the context for why the old implementation existed this way needs to be right there — available to the engineer reviewing the change and to the AI generating it.
Structured project memory. Tools and conventions so the reasoning behind decisions persists beyond the individual who made them. This means treating context documents — system descriptions, constraint inventories, edge case catalogs — as first-class artifacts that get versioned, reviewed, and maintained with the same rigor as code.
Integration contracts as explicit artifacts. Rather than letting service interfaces emerge organically from individually-generated components, defining and maintaining explicit contracts that AI tools can reference during generation. The contract becomes the source of truth for integration coherence, not the individual developer's mental model of how everything fits together.
Context-aware generation workflows. Configuring AI tools to ingest project context before generating code, rather than generating in a vacuum and hoping for coherence. This means investing in the scaffolding — the context files, the system prompts, the reference documents — that turn AI from a talented but amnesiac intern into a contributor who understands the system they're working within.
None of this is revolutionary. It's the kind of engineering discipline that good teams have always practiced. What's different is the urgency. When humans wrote all the code, context accumulated naturally — slowly, and with gaps, but it accumulated. When AI generates code at 10x the velocity, context dissipates at 10x the rate unless you deliberately counteract it.
The Assessment Gap
The biggest opportunity right now isn't in tooling — it's in assessment.
Most engineering organizations have no way to measure their exposure to these new forms of debt. They can tell you their test coverage percentage, their deployment frequency, their mean time to recovery. They cannot tell you how much institutional context has been lost in the last six months of AI-assisted development. They cannot quantify how many of their AI-generated components have integration assumptions that conflict with each other. They cannot assess whether their team's comprehension of the codebase has kept pace with its growth.
This is the gap that needs to be closed first. Before you can manage context debt, comprehension debt, and integration debt, you need to be able to see them. And right now, almost nobody can.
What This Means
If you're leading an engineering organization that's adopting AI-assisted development — and at this point, that's nearly everyone — the question isn't whether these new forms of debt are accumulating. They are. The question is whether you're managing them deliberately or discovering them during incidents.
The organizations that will thrive in the AI era aren't the ones that generate code fastest. They're the ones that maintain the richest context while moving fast. That's a different capability than what most teams are building right now, and it's one that compounds over time. The team that invests in context architecture today will be moving faster and more safely a year from now. The team that optimizes only for generation velocity will be drowning in debt they can't see and can't name.
The old tech debt conversation was about code quality. The new one is about knowledge architecture. And it's just getting started.
Michael Tuszynski is the founder of MPT Solutions, where he writes about AI strategy, cloud architecture, and engineering leadership. With 25 years in software — including six years as a Senior Solutions Architect at AWS and a stint as CTO at Fandor — he focuses on helping teams adopt AI-assisted development without sacrificing the institutional context that makes their systems work.
Previously: This Above All: To Thine Own Context Be True — on why context management matters more than prompt engineering.
