Definition. Technical debt is a categorizable set of shortcuts in a codebase with a measurable ongoing cost — not a vague description of messy code. Prioritizing it requires measuring that cost.
Why "messy code" is the wrong frame
Treating technical debt as a vague quality complaint makes it impossible to prioritize against feature work, because "this code is messy" has no comparable unit to "this feature drives revenue." The useful frame borrows directly from the financial metaphor: debt was taken on for a reason, it accrues interest in the form of ongoing cost, and paying it down is a decision that should be justified the same way any other engineering investment is — with a measured cost and a measured benefit.
Categories of technical debt
- Deliberate, documented: a known shortcut taken consciously, with a note on why and what the proper fix looks like.
- Deliberate, undocumented: a shortcut someone knew about but didn't record — the knowledge leaves when they do.
- Accidental, discovered: a design that seemed sound but proved wrong as the system grew — not a mistake at the time, a mismatch that emerged.
- Accidental, undiscovered: the most dangerous category — debt nobody has identified yet, silently accruing cost.
How to measure the cost, not just note the existence
Three proxies make debt cost comparable to feature-work cost: velocity drag (how much longer similar-sized features take to ship in the affected area versus elsewhere in the codebase), defect density (how disproportionately often bugs originate from that code relative to its size), and onboarding cost (how long it takes a new engineer to make a safe change there without senior guidance). None of these require exotic tooling — they require deliberately tracking outcomes by code area over time.
Prioritizing what to pay down first
| Signal | What it suggests |
|---|---|
| High velocity drag + high change frequency | Pay down first — the cost compounds on every touch |
| High defect density + customer-facing | Pay down first — direct cost to product quality |
| High cost but rarely touched code | Lower priority — the debt exists but rarely accrues interest |
| Isolated, well-contained debt | Lower priority — doesn't spread cost to adjacent systems |
Frequently asked questions
Is all technical debt bad and worth fixing?
No — deliberate, documented debt taken for a real reason can be sound. The problem is undocumented, accidental debt nobody is tracking.
How do you measure the cost of technical debt?
Track velocity drag, defect density, and onboarding cost in the affected area versus the rest of the codebase.
What is the difference between technical debt and just bad code?
Debt implies a trade-off made for a reason that made sense at the time. Bad code is a defect with no offsetting benefit.