Technical debt is the cost of future work created when you choose a faster solution instead of a better one in code. The term, coined by Ward Cunningham in 1992, is a loan metaphor — every shortcut charges interest in the form of slower changes, more bugs and more expensive maintenance. This article shows how to recognize debt, how to measure it and how to plan repayment without going bankrupt.
Key takeaway: Technical debt is not evil — every system has some. The evil is debt that nobody manages. A practical rule: deliberate debt (a conscious shortcut) gets scheduled for repayment; accidental debt gets measured with tools and repaid as you go. The alarm point is when shipping a feature takes longer than writing it.
Where technical debt comes from
Debt does not come from laziness — it comes from time pressure and changing requirements. Typical sources in the projects I see:
- deadline pressure — a feature "for yesterday" written without tests or refactoring,
- changing requirements — code written for different business assumptions than the current ones,
- lack of knowledge — solutions that seemed good when written but are traps in practice,
- team rotation — every vendor change leaves code in a different style with different shortcuts,
- neglected updates — PHP, framework and library versions years behind support,
- copy-paste instead of abstraction — the same mechanism duplicated in a dozen places, each with its own bugs.
It is worth separating deliberate from accidental debt. Deliberate is a conscious decision: "we know this is a shortcut, we will come back to it after launch." Accidental is the result of haste or ignorance that nobody wrote down. The second kind grows fastest because it appears on no list — until it starts blocking the project. Martin Fowler developed the framework further, splitting debt into four types: prudent and reckless, deliberate and inadvertent. The most dangerous is reckless and inadvertent — quick workarounds without understanding the consequences, which nobody remembers.
How technical debt affects the business
Technical debt does not show up on invoices — it shows up as delays. Teams working in indebted code report the same three symptoms:
- slower releases — a feature that should take a day takes a week, because every change pulls in unpredictable side effects,
- more bugs — the fewer tests and the murkier the structure, the more often one fix breaks another element,
- harder onboarding — a new person needs months to understand the system, or cannot understand it at all,
- growing maintenance costs — old technology and knowledge that left with former employees raise the price of every hour of work,
- blocked growth — product decisions are made not on "what is worth doing" but "what can still be bolted on."
The point where debt becomes a management problem has a simple test: compare the time needed to ship a typical change with the time needed to write it. When shipping takes longer — debt has started to dominate the code.
How to measure technical debt
Debt cannot be counted to the last dollar, but it can be measured well enough to make decisions. Four practical metrics
- static analysis — PHPStan and Psalm return the number of type errors and suspicious constructs; the trend over time says more than the absolute number,
- test coverage — the percentage of code covered by tests, and even better: coverage of business-critical paths,
- change lead time — measured regularly (e.g. from commit to production) and broken down by stage; a lengthening trend is the cleanest signal of growing debt,
- regression frequency — how many changes introduce fixes elsewhere; a growing number means modules are too intertwined,
- dependency age — how many versions behind your libraries are, and how many are out of security support.
The full picture comes from a legacy code audit — a review of architecture, security and performance with a roadmap. Metrics without a debt map say "it is bad"; a map says "here and here, in this order."
How to repay technical debt
The most common mistake is treating repayment as a separate project — "first six months of cleanup, then back to features." Such a project almost always loses to business pressure. Proven approaches look different:
- the scout rule — leave the code slightly better than you found it, with every change; it compounds surprisingly fast,
- a debt budget — a fixed share of team time (typically 10–20%) goes to repayment and technical cleanup, planned in advance,
- repayment in passing — a module you are already changing for a feature gets refactored at the same time; the cheapest form of repayment,
- modular refactoring — the highest-risk modules get their own planned modernization project,
- stop creating new debt — new code ships with tests, static analysis and code review; debt repaid while new debt keeps accumulating never gets paid off.
The key is tying repayment to the business. "Refactoring the billing module" sounds like a cost. "Cutting the time to ship billing changes from two weeks to two days" sounds like an investment — and it is one.
Technical debt and legacy code
Technical debt and legacy code are two sides of the same coin. Legacy code is code that survived and still works. Technical debt is the shortcuts accumulated inside it, whose repayment is the condition for further development. A system can be old with low debt (small, stable, well tested) — or young and heavily indebted (written in haste last year).
That is why the "what next" decision depends not on the age of the code but on the level of debt and business plans. If you plan to grow — the debt must be repaid, and the tools and sequence of work are laid out in the legacy code refactoring guide and in Legacy Code Modernization — Step by Step. If the system is meant to live without changes — security and updates are enough.
Three things to start this week
Three actions that need no project or budget
- Run PHPStan at its lowest level and record the error count — that is your baseline. Repeat the measurement monthly.
- Check how many dependencies are out of security support —
composer outdatedand vulnerability databases will show you in fifteen minutes. - Measure the time from commit to production for the last ten releases — if it grew, you have your answer about where it hurts most.
Those three numbers are enough to turn the conversation about technical debt from a conversation about feelings into a conversation about data.
Frequently asked questions
How is technical debt different from legacy code?
Legacy code is old code that still works and is in use. Technical debt is the accumulated shortcuts inside it — deliberate or accidental. Old code can have low debt, and brand-new code can be heavily indebted. Debt is about quality decisions; legacy is about age.
Can technical debt be repaid completely?
No, and that should not be the goal. Part of the debt consists of conscious, profitable decisions — like shipping a feature fast before an important deadline. The goal is managing debt: knowing its level, planning repayment for the most expensive items and zero tolerance for new accidental debt.
When does technical debt become critical?
When it blocks business goals: releases take weeks, regression bugs appear with every change, and finding people who understand the system is nearly impossible. Another signal is the moment the team starts planning work around the problems instead of solving them.
How much does repaying technical debt cost?
It depends on scale, but the starting point is not expensive. A technical audit gives you a debt map and a repayment roadmap, and further costs spread across modernization stages you would run alongside product development anyway. The full breakdown is covered in the modernization guide.