Not all technical debt is bad. Some of it is the only reason you shipped at all. The mistake teams make isn't taking on debt — it's failing to distinguish between the kinds, and treating all of it as something to be ashamed of.
A working taxonomy
After a decade of cleanup projects across client codebases, we sort technical debt into four buckets:
- Deliberate, short-term."We're hardcoding the country list because we ship Tuesday and we'll come back to it." Fine, as long as you do come back.
- Deliberate, long-term."We chose Postgres over a graph DB knowing we'll pay for some queries forever." Fine, as long as the trade was real.
- Accidental, recoverable."Nobody wrote tests for the billing module and now we're scared to touch it." Recoverable with effort.
- Accidental, structural."The schema assumed one currency and now we have eight." Often a rewrite.
The kind worth keeping
Concrete examples we've advised clients to not fix:
- Duplicated code across two services that will probably merge in a year.
- A slow admin query that runs once a week and nobody complains about.
- A janky internal tool that ten people use and nobody is hiring more of.
The kind to pay down now
Conversely, some debt compounds fast and gets exponentially worse. Pay these down before they own your roadmap:
- Anything around auth.Auth bugs become security bugs. Don't let auth code rot.
- Anything around money. Pricing, billing, refunds. The cost of bugs here is direct.
- Anything in the deploy or rollback path.If you're scared to deploy, you'll deploy less, and your debt grows.
- Anything that blocks new feature work.If a team avoids a module because it's scary, the cost is the features you're not building.
Writing it down
Every piece of deliberate debt should have a comment, a ticket, or a design doc explaining the trade. The cost of undocumented debt isn't the debt — it's the future engineer who can't tell whether the weird thing is a mistake or a deliberate choice, and spends a week finding out.
We do technical audits for clients that produce exactly this kind of taxonomy: what to keep, what to pay down, what to rewrite. Tell us about your codebaseif you're sizing one up.
End of article · Thanks for reading