Technical debt: how to spot it and pay it down before it blocks development
Every system has technical debt. The trouble starts when nobody knows how much there is or what it costs. Below I describe how to recognise it, how to measure it and how to pay it down without stopping development.
What technical debt is
Technical debt is the gap between how a system is built and how it should be built to be easy to develop further. Sometimes it is taken on deliberately: the deadline matters more than the perfect solution, so we take a shortcut. That is a reasonable decision, as long as someone writes down what is left to fix.
More often debt builds up quietly. Requirements change, new people add code, and nobody has time to tidy up what already works. The debt itself is not the problem. The interest is: every change in an indebted area takes longer and carries a higher risk of bugs.
How to spot it
The first signal usually comes not from the code but from the schedule:
- simple changes take longer and longer, and estimates grow for no obvious reason,
- more and more bugs come back after each release, often in places nobody touched,
- the team is afraid to change certain modules and works around them,
- a new person needs weeks to understand the system, because the knowledge lives in people’s heads rather than in documentation,
- a release requires manual steps that only one person knows.
If you recognise two or three of these symptoms, the debt is no longer a hidden cost.
How to measure it
Before you start paying it down, you need to know where the debt is and what it costs. In an audit I look at three things:
- Where the code changes most. Repository history shows the modules touched most often. Debt in code nobody touches costs little. Debt in a module changed every week costs a lot.
- Where most bugs come from. Matching bug reports to modules usually points to the same few places.
- What blocks the plans. A conversation about what the company wants to build over the next year shows which debt will get in the way.
Static analysis tools help, but on their own they produce a long list of warnings with no priorities. Priority only emerges when you combine code quality with how often and why the code is changed.
How to pay it down
Debt is rarely paid off with one big rewrite. Such projects take longer than planned, and the old system still has to be developed in the meantime. Paying in instalments works better:
- Start with tests in the areas you want to improve. Without them every refactoring is guesswork about whether you broke something.
- Fix things as you go. If the team adds a feature to an indebted module, include tidying it up in the estimate.
- Reserve fixed time for repayment, e.g. 15–20% of every iteration, instead of waiting for a “quieter period” that never comes.
- Record deliberate shortcuts. A short note on what was done quickly and why is enough for someone to know what to fix six months later.
- Automate releases. Manual steps are process debt that slows down every change.
Rewriting a system from scratch makes sense when the architecture prevents you from delivering your business plans, not when the code is merely untidy.
When an audit is worth it
An external audit is useful when development slows down noticeably, when you take over a system from another vendor, or before a larger investment in the product. An independent assessment shows where the debt is, what it costs and where to start, without defending earlier decisions.
Audits also often uncover things nobody knew about. I have come across passwords stored directly in code and software used without a licence. Findings like these are not just technical debt but real legal and security risks that are better discovered before they surface on their own.