Technical debt is the most misunderstood concept in software engineering. It gets used as a catch-all for everything engineers dislike about a codebase — poor naming, missing tests, outdated frameworks, architectural decisions that didn't age well. But not all of these problems are equivalent, and treating them as if they are leads to poor prioritisation and wasted refactoring effort.
This is a framework for thinking about technical debt systematically: what it actually is, how to measure it, how to prioritise it, and how to explain it to people who have never written code.
What Technical Debt Actually Is
The original metaphor, coined by Ward Cunningham, was specific: technical debt is the implied cost of future rework caused by choosing an expedient solution now instead of a better approach that would take longer. Like financial debt, it accrues interest — the longer you carry it, the more expensive it becomes to address.
The key insight is that not all suboptimal code is debt. Some of it is just bad code. The distinction matters because debt has a repayment logic — there is a point at which paying it down returns a positive ROI. Bad code that nobody touches, in a part of the system that never changes, may not be worth addressing at all.
Technical debt worth addressing has these characteristics:
- It exists in code that is actively changed or heavily depended upon
- It increases the cost of future changes (slows development velocity)
- The cost of carrying it exceeds the cost of addressing it over the relevant time horizon
Categories of Technical Debt
Understanding the type of debt helps determine the right response:
Architectural debt — Fundamental structural decisions that constrain the system's ability to evolve. Examples: a monolith that needs to be decomposed, a synchronous architecture that needs async messaging, a shared database that prevents independent scaling of services. This is the most expensive debt to carry and the most expensive to pay down.
Dependency debt — Outdated or deprecated libraries, frameworks, and runtime versions. Node 14, React 16, unmaintained packages. This creates security exposure and accumulates as the gap between the current version and the ecosystem widens, making upgrades progressively more disruptive.
Test debt — Insufficient test coverage, especially around critical paths and edge cases. Code without tests cannot be safely refactored — which means other types of debt become locked in place.
Design debt — Poor abstractions, duplicated logic, overly coupled modules, missing separation of concerns. This is the most common form and the most tractable — it can be addressed incrementally without architectural change.
Documentation debt — Undocumented systems, stale documentation, implicit knowledge held only in engineers' heads. This does not slow down the engineers who wrote the code. It slows down everyone else, indefinitely.
Identifying Debt Systematically
An effective debt audit combines quantitative metrics with qualitative engineering judgment.
Quantitative signals:
- Cyclomatic complexity scores — high complexity correlates with bugs and maintenance cost
- Code churn rate — files that change frequently and have high complexity are the highest-risk combination
- Test coverage percentage, specifically on high-churn files
- Dependency age and known CVE count
- Build and deployment time trends
Qualitative signals (gathered through engineering team interviews):
- Which parts of the codebase do engineers avoid changing?
- Which features consistently take longer than estimated?
- Which areas generate the most post-deployment bug reports?
- What do new engineers struggle to understand after their first 30 days?
The intersection of these signals — high quantitative debt indicators in areas engineers describe as painful to work in — is where to focus remediation effort first.
Quantifying the Business Impact
The conversation that must happen before significant debt remediation investment is the business impact conversation. Engineering leaders who present debt in purely technical terms lose the argument. The framing that works is velocity and risk.
Velocity framing: Model the relationship between debt and development speed. A common pattern is feature development taking 40–60% longer than it should in heavily indebted codebases, due to the overhead of working around structural constraints. If your team ships 2 features per sprint in the current state and could ship 3 with the debt addressed, the annual delta is 26 additional feature deliveries. What is the revenue or cost-avoidance value of that?
Risk framing: Unpatched dependencies and untested critical paths are security and reliability risks with direct business consequences. A breach or major outage has quantifiable cost: remediation, reputational damage, contractual penalties, customer churn. The question is not "what does it cost to fix the debt?" but "what is the expected cost of the incident that the debt makes more likely?"
Hiring and retention framing: Engineers leave codebases they are embarrassed to work in. The cost of replacing an experienced engineer — recruiting, onboarding, and the 6–12 month ramp to full productivity — is typically €60,000–€150,000. If technical debt is a retention risk, that cost belongs in the ROI calculation.
Prioritisation Framework
With a debt inventory and business impact estimates, prioritisation follows a two-axis model:
Axis 1: Business impact — How much does this debt reduce velocity, increase risk, or affect retention?
Axis 2: Remediation cost — How long does it take to address this debt item, and what is the risk of the remediation itself?
High impact, low cost: address immediately. These are quick wins — the modernisations and refactors that pay back in weeks.
High impact, high cost: plan carefully and invest. These are architectural changes that require dedicated capacity, phased delivery, and stakeholder alignment.
Low impact, low cost: batch into normal development work. Address opportunistically when working in the area.
Low impact, high cost: do not address. This is debt that exists in stable, rarely-changed code. The ROI is negative; leave it alone.
The Strangler Fig Pattern
For architectural debt — the most disruptive to address — the strangler fig pattern is the safest approach. Rather than a big-bang rewrite (which is one of the highest-risk engineering strategies that exists), the pattern works by:
- Building new functionality in the target architecture
- Progressively migrating existing functionality from the old architecture to the new one, module by module
- Routing traffic to the new system as each component is migrated
- Decommissioning the old system once migration is complete
This approach keeps the system live and functional throughout the migration, allows the team to learn and adjust mid-process, and delivers incremental value rather than deferring everything to a final cutover.
Making Debt Remediation Sustainable
The organisations with the lowest debt levels are not those that periodically declare "debt sprints" — intensive periods of remediation followed by a return to debt-accumulating development practices. They are the ones that have made debt prevention a continuous part of normal development work.
The practices that prevent accumulation:
Definition of Done includes non-functional requirements. If test coverage, complexity limits, and dependency freshness are part of the criteria for considering a feature complete, they get addressed continuously rather than deferred.
Architectural review for significant changes. New features that touch the core data model or introduce new architectural patterns get reviewed before implementation. This catches expensive decisions before they are baked into the system.
Regular dependency maintenance. Monthly or quarterly dependency updates, automated where possible, prevent the compounding effect of version gaps.
Agreed complexity budgets. Setting team-level agreements about acceptable complexity metrics — and treating violations as bugs — gives engineers a shared language for resisting shortcuts.
Technical debt is not a failure of engineering discipline. It is an inevitable consequence of building software in conditions of uncertainty and time pressure. The organisations that manage it well are those that acknowledge it honestly, measure it systematically, and address it continuously — rather than pretending it does not exist until it becomes a crisis.