The Real Technical Debt Isn't in Your Codebase

Technical debt is one of the few metaphors engineering ever produced that travelled all the way up to the executive floor. The idea is elegant: a shortcut taken today — a quick hack, a skipped refactor, a copy-pasted module — is a kind of borrowing. It gets you moving now, but it accrues interest, and someday you pay it back with compound effort. Because the metaphor is so good, we hunt this debt relentlessly. We track it, we schedule paydown sprints, we argue about it in retrospectives. All of it aimed at the codebase.

And in aiming entirely at the codebase, we miss where the most expensive debt an organisation carries actually sits.

The debt that was never in the code

Think about what really compounds in a software organisation. It isn't mainly the hacky module — that's local, contained, and a competent engineer can pay it down in an afternoon. The debt that compounds catastrophically is the debt in the decisions nobody wrote down. The agreement that was reached verbally in a meeting and never captured. The assumption two departments each made differently and never reconciled. The "we all know what we meant" that turns out, eighteen months later, to have meant three different things to three different people.

This is debt in the most precise sense of the metaphor. You took a shortcut — you didn't do the slow, effortful work of making the agreement explicit, canonical, and signed — because making it explicit was tedious and everyone was busy and it felt like things were clear enough. That shortcut got you moving. And it accrues interest, paid every single time someone builds against a version of the truth that turns out to be wrong. The interest payment is a wrong build, a rework cycle, a dispute about what was actually promised. You are servicing a loan you forgot you took out, and the lender is your own past failure to write things down.

Why we hunt the wrong debt

The reason we look for technical debt in the code and not in the agreements is simple: the code is where we can see it. Code is concrete, inspectable, diff-able. There are tools that measure its complexity and flag its smells. Agreement debt has none of that. It's invisible precisely because it was never written anywhere — that's what makes it debt. You cannot run a linter over the things your organisation failed to decide explicitly. So we instrument the visible debt obsessively and let the invisible, more expensive debt accrue silently in the dark, because we have no instrument that points at it.

Consider how this plays out — illustrative, but familiar. A platform decision is made in a workshop. Everyone nods. Nobody captures the specific commitment, because it felt obvious in the room. Six months later, three teams have each built on a slightly different memory of what was decided. The integrations don't fit. The post-mortem calls it a technical problem and schedules a refactor. But there was nothing wrong with anyone's code. The debt was incurred in the workshop, the day a clear agreement was owed and an ambiguous memory was taken on instead. The codebase is paying interest on a loan the organisation took out in a meeting room.

AI just raised the interest rate

For a long time, agreement debt was survivable for the same reason all delivery problems were survivable: construction was slow enough to absorb it. When building took a quarter, there was time for the unwritten disagreements to surface and get reconciled before they did real damage. The slow pace was, in effect, making minimum payments on the debt automatically.

AI removed that. When an agent can build against an ambiguous agreement in an afternoon, the debt gets called in immediately and at full speed. Every unwritten assumption is now exercised the moment someone generates against it, and exercised again every time it's rebuilt. The same agreement debt that used to accrue slowly now compounds at machine speed. You didn't take on more debt than your organisation always carried — you just started paying a far higher rate of interest on it, because the thing that was quietly servicing it, the slowness of building, is gone.

Paying down the debt you can't see

The fix is not another pass over the codebase. It's to start treating the agreement the way we already treat code: as an artifact that must be made explicit, versioned, and signed — so that the debt of the unwritten decision stops being taken on in the first place. You pay down agreement debt by capturing the agreement, canonically, before it compounds. That's the entire premise of what we built Propel to do: to make the expensive, invisible debt visible and explicit at the point it's incurred, instead of letting the codebase pay interest on it forever.

Keep tracking the debt in your code; it's real and it matters. But understand that it was never your largest liability. The most expensive debt your organisation carries is in the things it agreed to and never wrote down — and at AI speed, that's the debt now compounding fastest.

Two kinds of debt, one of which you track

• Code debt. Shortcuts in the implementation. Visible, tracked, and increasingly cheap for an AI coding tool to repay.
• Agreement debt. Decisions taken and never written down. Invisible, untracked, and untouched by any coding tool.
• AI raised the interest rate on the second. AI-generated code piles more software on top of the undocumented decision, faster than anyone can reconstruct it.
• You pay it down at the point it is incurred. By capturing the agreement when it is made, rather than archaeologically, three releases later.