That framework migration you have put off for six years — the one cut from four roadmaps in a row because it was three engineer-months and no customer would notice — is now about a weekend of agent time plus a careful review.
That is not a small shift in priorities. It cancels a decade of engineering judgment about what is worth fixing.
Technical debt was always priced on two numbers: what it costs you to carry, and what it costs you to repay. We got very good at estimating the second one, and most debt decisions were really about the cost of paying it back. “Not worth it” almost always meant “the mechanical work costs too much,” not “the current state is fine.”
The mechanical work got cheap. So a large group of debt you were right to ignore is now worth paying off — and if your backlog still assumes 2023 prices, you are leaving free money on the table.
That is the good news, and it is genuinely good. Here is the part that should worry you. While the price of old debt fell, five new kinds of debt moved in, and none of them respond to the thing that made old debt cheap.
The cost of change collapsed for anything a machine can verify. It did not move at all for anything that requires a human to understand. Every new form of AI debt lives on the wrong side of that line.
This is part ten of Rethinking the SDLC. I’ve written before that AI makes code cheap to produce but not cheap to own. This piece is the balance sheet version of that argument.
The dividing line is machine verifiability, not difficulty#
Here is the test that re-prices everything, and it is not “how hard is this?”
Can a machine verify that the end state is correct?
If yes, the work is cheap now, however big it is. A framework migration across 400 files can be checked: the tests pass, the types check, the behavior is provably the same. Volume was the whole cost, and volume is what got cheap. The same goes for dependency upgrades, sweeping out retired APIs, removing dead code, formatting and lint cleanups, pulling out duplicated logic, adding types to an untyped codebase, splitting a god-file, and finally writing the tests you never wrote for existing behavior.
Spending a senior engineer’s week on a lockfile-shaped problem was always a bad trade. Now there is no defending it.
If no, nothing changed. Work whose correctness rests on a judgment — is this the right boundary, does this abstraction match the business, is this really how the domain works — costs exactly what it always cost, because the expensive part was never the typing. No test suite says “this is the right service boundary.” A machine can confirm that code agrees with itself. It cannot confirm that code agrees with reality.
So run your list of debt through that one question. Most teams find 60–70% of their backlog just got far cheaper, and the other 30–40% did not move an inch. That re-sort is worth an afternoon of anyone’s time.
Then notice the trap. Because the cheap group is now so cheap, teams will clear all of it and feel productive while the expensive group — where the real architectural risk lives — stays untouched. Paying down debt becomes another kind of speed theater. Clearing 400 lint warnings feels like progress. It is not the same as fixing the boundary that will cost you a quarter next year.
The five classes of AI debt#
These are not metaphors. Each one costs you something to carry, grows if you leave it, and has a specific way to pay it off.
1. Context debt#
The stale, scattered, unowned knowledge that steers agents. Runbooks describing a system from two refactors ago. Architecture notes that contradict the code. Conventions written down in three places with three different answers. Tool lists nobody maintains.
Carrying cost: wrong code, produced confidently, at machine speed. A human reading a doc that contradicts the code squints and asks someone. That doubt was an error-correction layer nobody ever named. Agents read documentation as fact. A stale page used to cost an afternoon in Slack. Now it is wrong instructions carried out at 3 AM.
Why it grows: every agent run that reads bad context produces artifacts that carry the same error, and those become context for the next run.
How to pay it off: a named owner, versioning next to the code, a clear way to retire old pages, and evals that check whether a doc still produces correct behavior. This is the debt that most directly caps agent quality, which is why knowledge infrastructure stopped being a documentation project.
2. Comprehension debt#
Code that works, passes its tests, is in production, and that nobody in the organization understands.
This is the debt I would watch most closely, because it is invisible by its very nature. There is no linter for it. Static analysis calls it fine. It looks exactly like well-understood code in every system you own — and it is the load-bearing input to every judgment call you will have to make later.
What it costs to carry: you cannot make architectural decisions about a system you do not understand. You cannot judge whether a change is safe, whether an abstraction should be reused, whether a boundary is right. Charity Majors puts it exactly: when you ship code faster than engineers can read it, “reliability degrades, institutional knowledge evaporates.”
Why it grows, and why it is the worst one: comprehension debt is the only kind that leaves you unable to judge your other debt. You cannot price a risk in a subsystem nobody understands. And it cannot be paid off cheaply, by definition — understanding is the one thing that did not get cheap.
How to pay it off: on purpose, at real cost, and on the calendar. Comprehension is the one thing on this list you cannot get as a side effect of shipping. So name the subsystems where human understanding is required — the ones where meaning changes: boundaries, contracts, data models, product behavior — assign them to people, and accept that the machine-checkable loops around them get no human attention at all.
Teams make the same mistake with attention that they make with money. Under sprint pressure they spend their understanding where it is cheapest to spend — on the diff that is easy to read — and skip it where it is expensive and necessary. Then the list they use to decide what to fix next gets written by people who no longer understand the systems they are pricing.
3. Permission debt#
The pile of credentials, grants, service accounts, tool access, and API keys that nobody audits and nobody dares remove.
Every engineering organization has always had this. What changed is who holds it. A stale over-permissioned service account used to sit unused; now it’s the credential an agent lane inherited because it was the one that worked.
What it costs to carry: blast radius. It is how a small agent mistake turns into a large incident — including the July 2025 case where a Replit agent deleted a live production database during a code freeze, affecting over 1,200 executive users. The agent didn’t escalate its own privileges. It used what it was given.
Why it grows: permissions get granted under time pressure and taken back never, so the pile only gets bigger. Then leaked secrets widen it further — GitGuardian’s 2026 report puts 28.6 million new secrets in public commits over the year, a 34% rise, and finds AI-assisted commits leaking at about double the baseline rate.
How to pay it off: credentials tied to one lane, allowing few actions, created fresh for each run and expiring in minutes. This is the one kind of debt where the fix is entirely mechanical and the payoff is immediate, which makes putting it off the hardest choice on this list to defend.
4. Harness debt#
The prompts, agent configurations, tool definitions, model pins, context-assembly logic, and eval suites that determine what your agents actually do.
This is the newest kind and the least managed. In most organizations it is a pile of untracked strings: a prompt someone tuned in March that now exists in four slightly different versions, tool definitions nobody owns, model versions pinned in one place and floating in another, context assembly with no tests.
What it costs to carry: behavior you cannot predict, and no way to diagnose it. When output quality drops, you cannot tell whether the model changed, the prompt drifted, the context source went stale, or a tool definition broke. And it is not free even when nothing is happening — Anthropic’s engineering work notes that tool definitions alone can eat ~55k tokens before any work begins, so a tool list nobody trims makes every single run worse.
Why it grows: the harness is a production system that everyone treats as configuration. Its behavior emerges from the whole, so nobody refactors it. They add another line to the prompt and move on — the same slow pile-up that produced every legacy system you have ever inherited.
How to pay it off: treat the harness as code. Versioned, reviewed, owned by name, with an eval suite that runs on every change and a changelog that lets you trace a shift in behavior back to a specific edit. If you cannot answer “what changed in the harness last week?”, you cannot operate it.
5. Verification debt#
Gates that don’t gate. Tests that cannot fail. Suites with 90% coverage and no way to spot wrong code. continue-on-error on the stage that was noisy. Quarantined tests with no owner and no expiry date. Retry-on-failure standing in for a diagnosis.
What it costs to carry: you are flying on instruments that read green whatever the weather. This is worse than having no gates at all. No gates makes people careful. Broken gates make people confident.
Why it grows: verification debt is what lets the other four pile up unnoticed. It is the debt that hides debt.
How to pay it off: mutation testing to audit the suite, a fail-closed rule on every gate, expiry dates on every exception, and independence between the thing that writes code and the thing that checks it. I took this apart properly in the proof-of-behavior piece.
Classic debt didn’t stop accumulating, either#
One thing I don’t want to suggest: that classic debt is solved now because it is cheap to pay off. The evidence says it is piling up faster than before.
A January 2026 study of autonomous coding agents found static-analysis warnings up 18% and cognitive complexity up 39%, and described “sustained agent-induced technical debt even when velocity advantages fade.” Read that last part twice: the debt stayed after the speed benefit stopped. GitClear’s code-quality analysis shows how it happens: duplication rising while refactoring falls, and most of the churn sitting in recently written code. That combination is the signature of a system that tidies up less than it produces.
The reason is simple and worth naming. Refactoring is a judgment: you decide that two things are really the same thing and should become one. Copying is mechanical. When generating code is free, the cheapest path is always another copy rather than noticing and merging. Agents will duplicate instead of abstracting unless something stops them, because a copy is correct right here, and merging needs a view of the whole.
So you get both effects at once: classic debt is cheaper to repay and being created faster. Whether you come out ahead depends entirely on whether you actually do the paydown — on purpose, with budget and time set aside, rather than as something people get to on a spare afternoon. Nobody has a spare afternoon.
How to price any debt item now#
Four questions. Ask them in order.
1. Can a machine verify the end state of the fix? Yes → paying it off is cheap, however big it is. Schedule it, batch it, run it. No → paying it off costs the same as it always did, in human time, and it competes with your scarcest resource.
2. Does the carrying cost compound with agent volume? This is the multiplier nobody applies. Context debt, permission debt, and verification debt all do more damage the more agent runs you do. A stale runbook cost you one confused engineer a month at human speed. At fleet speed it costs forty wrong runs a day. Debt whose cost grows with volume should be paid off before debt whose cost stays flat — even if the flat one looks bigger today.
3. Does it block your ability to assess other debt? Comprehension debt and verification debt do. They attack your ability to know the state of your own system. Treat them as more urgent than their direct cost suggests, because everything else on your list was estimated with instruments they have already spoiled.
4. What’s the blast radius if it’s never repaid? Permission debt has the widest and fastest failure mode. Context debt produces the most wrong work. Comprehension debt produces the worst decisions. Harness debt produces the most confusing incidents. Verification debt lets all of them through.
Run your list through those four and the order that falls out is usually this: permission debt first (mechanical, fast, wide blast radius), then verification debt (it is hiding everything else), then context debt (it grows with volume), then the machine-checkable classic backlog (cheap now, do it in batches), and finally comprehension and architectural debt as funded, ongoing human work rather than a project.
Six moves#
- Re-sort your debt list by whether a machine can check the result, not by size. One afternoon. You will find a pile of “too expensive” items that are now weekend work, and the handful that genuinely need senior humans.
- Run one large mechanical paydown this quarter, as a batch. The deferred migration, the untyped module, the duplicated logic. Prove the new numbers to yourself and to your leadership with a real result.
- Audit the credentials your agents can reach and cut the destroy permission. The best return per hour on this whole list, and it is pure mechanical work.
- Put the harness under version control with an eval suite. Prompts, tool definitions, model pins, context assembly. If it determines behavior, it’s code.
- Name an owner for every doc an agent can read, and delete the ones nobody will own. A document with no owner is not documentation, it is a rumour with formatting — and deleting an out-of-date one is a production change worth making.
- Start measuring comprehension explicitly. Per critical subsystem: can at least two people explain how it works and why it’s shaped that way? Track it, report it, and treat a zero as an incident waiting to happen. It is the only one of these with no tooling, which is exactly why it needs a number.
Debt was always about optionality#
Technical debt is a good metaphor, but not because of the interest. It is because debt limits what you can do next. A system with a lot of debt has fewer futures open to it.
That is why comprehension debt is the one I would lose sleep over. Classic debt made change expensive, and you could still choose to pay. Comprehension debt makes change impossible to judge. You cannot tell whether a change is safe, so you either freeze or you guess. Both are worse than expensive.
And here is what makes this moment genuinely interesting rather than just frightening. Every one of these five can be paid off, and three of them can be paid off mechanically. This is not a story about decay you cannot stop. It is a story about a balance sheet that got re-priced while nobody updated the list — and the organizations that update it first get to spend the next two years fixing things everyone else wrote off as permanent.
So here’s the exercise. Pick your three most critical subsystems. For each one, ask whether two people can explain how it works and why it’s shaped that way.
Where the answer is no, you don’t have technical debt. You have a system your organization no longer owns — and no amount of cheap execution will buy that back.
I lead AI transformation for a global SaaS platform, and the five debt classes above are the ones I actually track. If you’ve found a sixth, or you’re measuring comprehension in a way that works, I want to hear it — that’s the one I’m least satisfied with. Find me on X, LinkedIn, or Telegram.