Understanding Technical Debt (And When to Pay It Down)
Technical debt isn't always bad. Here's a framework for deciding when to live with it and when to fix it before it buries you.
Every codebase accumulates technical debt. The question isn’t whether you have it — you do — it’s whether you’re making conscious choices about it.
Debt Is a Tool, Not a Failure
Ward Cunningham, who coined the term, meant it as a metaphor: sometimes you ship something suboptimal on purpose, like taking out a loan, knowing you’ll pay interest until you fix it. The problem isn’t the debt itself. It’s debt you didn’t choose to take on, or debt you forgot about.
Three Categories Worth Distinguishing
1. Deliberate, documented debt
You made a call: “We’ll use this quick implementation for now and revisit after launch.” You wrote it down. You know the cost. This is fine — this is how software ships.
2. Inadvertent debt
Code written by someone who didn’t know a better way at the time. No one’s fault. Discovered during a code review or audit. This is the most common kind and the most fixable.
3. Reckless debt
“We don’t have time to do it right.” Repeated shortcuts with no plan to address them. This is where projects go to die.
When to Pay It Down
Some heuristics I use with clients:
- Before adding a major feature on top of a shaky foundation — debt compounds
- After hiring — onboarding is hard enough without code that requires tribal knowledge to navigate
- When velocity noticeably drops — if estimates keep surprising you, the codebase is fighting you
- During a calm sprint — proactive refactoring is cheaper than reactive debugging
When to Leave It Alone
Not all debt is worth paying. If a module works, hasn’t changed in two years, and no one needs to touch it, leave it. The interest rate on dormant code is zero.
The highest-leverage thing you can do with technical debt is simply make it visible. Name it. Track it. Then you can make real decisions about it instead of reacting to it.