Technical debt: what it is and how to pay it down
Technical debt is the extra time every change costs because of past shortcuts. How to spot it, measure it simply and pay it down without a rewrite.
By Sohail Hussain21 November 20266 min read
Technical debt is the extra time and risk every future change carries because of shortcuts taken earlier: code written fast to meet a deadline, a design that made sense for ten customers but not a thousand, missing tests, outdated libraries. Like a loan, it lets you move faster now, and charges interest later in slower features and more bugs. You pay it down by fixing it in small steps, focused on the parts of the code you change most, while continuing to ship features, not by stopping everything for a rewrite.
Some debt is a good decision. An MVP built carefully but quickly carries debt by design, and that is fine. The problem is debt nobody chose, nobody tracks and nobody pays.
Where does the term come from, and what counts as debt?
Ward Cunningham coined the metaphor in a 1992 experience report, describing shipping first-time code as "going into debt" and rewriting it as understanding improved as paying it back. His point was about learning: you write code with what you know today, and as you learn more about the problem, the code should be updated to match.
In practice, teams use the term for several kinds of shortfall:
| Kind | What it looks like | Typical interest |
|---|---|---|
| Code | Duplicated logic, very long functions, unclear names | Changes take longer and break other things |
| Design | A data model or structure that no longer fits the product | Every new feature needs a workaround |
| Tests | Few or no automated tests on important paths | Fear of changing anything; bugs found by customers |
| Dependencies | Old framework and library versions | Security risk, blocked upgrades, missing features |
| Infrastructure | Manual deploys, no staging, no monitoring | Slow, risky releases and long outages |
| Knowledge | No documentation; one person understands a part | Work stops when that person is away |
Missing features and bugs are not debt. A bug is the product doing the wrong thing. Debt is the product doing the right thing in a way that makes the next change harder.
Is technical debt always bad?
No. Taking it on deliberately is often the right call. An MVP that tests whether customers will pay should not be engineered for a million users; a feature promised to a large customer for Monday may justify a shortcut on Friday. The pillar guide on how to build a SaaS product argues for exactly that kind of speed early on.
What makes debt harmful is the same thing that makes financial debt harmful: not knowing how much you owe. Deliberate debt is written down, with the reason and the condition for paying it back ("rebuild the import when we pass fifty customers"). Accidental debt piles up without anyone noticing, until every estimate starts with "it depends what we find".
How do you know debt is costing you?
These are the signs we see most often when a team asks us for help through our web app and SaaS development or dedicated team work:
- Estimates keep growing for changes that sound small, and developers hedge every one.
- The same areas keep breaking. Bug reports cluster in a few parts of the code.
- People avoid certain files. One module everyone is afraid to touch, or only one person can.
- Releases are events. Deploying needs a specific person, a checklist and a quiet afternoon.
- Upgrades are blocked. The framework is several major versions behind, and upgrading "would take months".
- New developers take weeks to be useful, because nothing explains how the parts fit.
Any one of these is a prompt to look. Several together usually mean the interest payments have become a large share of the team's time.
How do you measure it without a consultant?
You do not need a precise number. You need enough to decide where to spend effort.
Track two delivery measures. DORA, the research programme on software delivery, defines a small set of delivery metrics. Two are easy to start with: change lead time, how long a change takes from commit to production, and change fail rate, the share of deployments that need a fix or rollback. If both are getting worse, debt is a likely cause.
Find the hotspots. The files changed most often and the files with the most bug fixes are where debt costs the most, because that is where you pay interest every week. Version control history shows both. Debt in code nobody touches is cheap; leave it.
Keep a debt register. A simple list, in the issue tracker, of known debt: what it is, where, what it slows down, and a rough cost to fix. Developers add to it when they meet something; it is reviewed when planning. It turns "the code is bad" into choices.
Check dependency age. A list of your main dependencies with how far behind the current version each is. Major versions behind on the framework, database driver or auth library is high-interest debt, because security fixes stop eventually.
How do you pay it down without stopping feature work?
Fix debt where features are going. Before building a feature in a messy area, spend part of the estimate cleaning up that area first. The clean-up pays back immediately in the feature, and the founder sees the return.
Reserve a steady share of time. Many teams set aside a fixed share of each sprint for the debt register. A steady allowance beats an occasional "clean-up month", which is the first thing cancelled when a deadline appears.
Add tests before changing risky code. Tests that pin down current behaviour make the refactoring safe and stay useful afterwards. Start with the paths that handle money, permissions and data.
Add types where the data comes in. In TypeScript projects, much accidental complexity hides in untyped API responses and any. Typing them is cheap and catches real bugs; our JSON to TypeScript tool gives you a starting interface from a sample response.
Replace big pieces gradually. For a module that has to be rebuilt, build the new version alongside the old, move one route or one customer group at a time, and remove the old code when nothing uses it. It is slower than a rewrite on paper and much safer in practice.
Keep dependencies moving. Small, regular upgrades are cheap. One upgrade across four major versions is a project. Automated dependency update tools turn this into routine review.
When is a rewrite the right answer?
Rarely, and less often than it feels from inside a messy codebase. Rewrites take longer than estimated, because the old code contains years of fixes for cases nobody remembers, and while the rewrite runs, the product stands still.
A rewrite can be justified when the platform itself is the problem, such as an unsupported framework or a no-code tool the product has outgrown; when the product has changed so much that the old design fits none of it; or when the code is small enough that rewriting is a few weeks of work. Even then, rewrite in slices and ship each one, rather than switching everything on one day.
If you have inherited a codebase and do not yet know how much debt it holds, start with an audit; how to take over an existing codebase describes the one we run. For products that need steady upkeep rather than a project, website and app maintenance covers what ongoing care involves.
Was this guide useful?