What Is Technical Debt? Definition, Types and How to Measure It

repowise team11 min read
On this page

Technical debt is the extra cost that every future change pays because code was written, or left, in a form that is harder to change than it needs to be. You measure it by finding where that cost lands: files that are complex, change often, keep needing bug fixes, or that only one person understands.

This guide defines the term, lists the kinds of debt with examples, shows how to measure technical debt with commands you can run today, and puts numbers on what is normal using 195 public repositories.

What is technical debt?

Technical debt is a metaphor for the interest you pay on shortcuts. Ward Cunningham introduced it in his 1992 OOPSLA experience report on the WyCash portfolio system: shipping code that does not yet reflect what you have learned is like borrowing money, fine in the short run, and costly if you never pay it back. The principal is the work needed to fix the code. The interest is the slowdown on every change that touches it.

Two things follow from the metaphor. Debt is not the same as bad code: a deliberate shortcut taken to hit a launch is a loan, and a loan can be a good decision. And debt is only expensive where it accrues interest. Code that is ugly but stable costs almost nothing, because nobody pays the interest.

What are the types of technical debt?

Technical debt comes in several kinds, and the kind decides how you find it and what fixing it costs. Martin Fowler's technical debt quadrant sorts debt by intent (deliberate or inadvertent) and by judgment (prudent or reckless). The table below sorts it by where it lives, which is more useful when you are looking for it.

KindExampleHow it shows up
Code debtA 600-line function with nested conditionsHigh complexity, slow reviews, bugs on every edit
Design debtA module that every other module importsOne file in the middle of every change, wide blast radius
Dependency debtAn unmaintained library, a framework two majors behindBlocked upgrades, unpatched advisories
Test debtA hot file with no testsFear of changing it, regressions that tests would catch
Documentation debtA README that describes last year's architectureSlow onboarding, wrong answers from people and agents
Dead codeUnused files, exports and packagesNoise in search, false confidence in what is in use
Knowledge debtA subsystem only one engineer has touchedA bus factor of 1, stalled work when they are away
Infrastructure debtHand-run deploys, flaky CIReleases that need a person, slow feedback

Scroll the table sideways to see every column.

Fowler's quadrant answers a different question: was the debt a decision? Reckless and inadvertent debt is the kind to fix first, because the team did not know it was borrowing.

How do you measure technical debt?

You measure technical debt by combining a few signals per file, because no single number captures it. A complexity score tells you which code is hard to read. It does not tell you whether anyone reads it. Git history supplies the other half: how often a file changes, how often it needs a fix, and who has touched it.

SignalWhat it tells youCommand or tool
ComplexityWhere code is hard to changelizard, radon, gocyclo, SonarQube cognitive complexity
ChurnWhere work actually happensgit log --name-only (below)
Churn times complexityWhere debt charges interestHotspot analysis
Bug-fix historyWhere the debt already caused defectsCommits matching fix, linked issues
Dead codeCode that costs reading time and does nothingKnip, vulture, deadcode
DuplicationFixes that must be made in several placesjscpd
OwnershipWhere knowledge is thingit shortlog, bus factor

Scroll the table sideways to see every column.

Step 1: find where work happens (churn)

Count how many commits touched each file in the last 90 days:

bash
git log --since="90 days ago" --no-merges --name-only --format= \
  | grep -v '^$' | sort | uniq -c | sort -rn | head -20

The top of this list is where your team spends its time. Read code churn for line-level variants that separate healthy iteration from rework.

Step 2: find what is hard to change (complexity)

lizard supports most mainstream languages and lists the functions over a cyclomatic complexity threshold:

bash
pip install lizard
lizard -C 15 -w src/

-C 15 sets the threshold and -w prints only the warnings. For the difference between cyclomatic and cognitive complexity, and per-language tools, see nested vs cyclomatic complexity.

Step 3: cross the two

A hotspot is a file that is both complex and frequently changed, and it is where technical debt costs the most. Take the top 20 files from step 1 and look up their complexity from step 2. A file that appears in both lists is a candidate. The full method, with a script that joins the two, is in code hotspots with git.

Step 4: check the cost already paid (bug fixes)

Count fix commits per file over the last 180 days:

bash
git log --since="180 days ago" --no-merges -i --grep='fix' --name-only --format= \
  | grep -v '^$' | sort | uniq -c | sort -rn | head -20

This depends on commit message discipline, so treat it as a ranking and not a count. A file that is complex, busy and on this list is paying interest in production.

Step 5: add dead code, duplication and ownership

Dead code is the cheapest debt to retire, since deleting it needs no design. How to find dead code covers a tool per language. Duplication is measured with jscpd src/. Ownership comes from git shortlog -sn --since="12 months ago" -- path/, and a file where one author wrote 80% or more of the commits has a bus factor of 1.

Doing all of it in one pass with repowise

repowise runs these signals together on a local index and scores every file from 0 to 10 across the engine's 59 detectors:

bash
pip install repowise
repowise init --yes --no-prose
repowise health

repowise health prints a ranked Fix first list built from the dependency graph, git history, bug history and test coverage, with the first edit and the test command for each item. That is the worklist step 3 and step 4 produce by hand, with reach (how many files import the code) added. To order that list by impact per effort, see how to prioritize technical debt.

What about a technical debt ratio?

The technical debt ratio is estimated remediation cost divided by the estimated cost of developing the code. It comes from the SQALE method, and static analysis tools such as SonarQube report it as a percentage with a letter grade. It is easy to put on a dashboard. Its weakness is that remediation cost is an estimate built from rule violations, so the same ratio can describe a quiet file and a hotspot.

The tools disagree on what they count, and few show evidence that their score tracks bugs. Technical debt measurement tools compared goes through what each score includes. Our approach is to rank by where history shows the cost lands, then use a ratio as a trend line.

What does technical debt look like in real codebases?

In 195 popular open-source repositories, debt is concentrated in a small number of files, and those files are the ones that change. We analysed 195 of the public repositories indexed on repowise.dev (1,000+ GitHub stars each, 253,688 production source files, November 2026). Every figure covers production code only, with tests, generated code, vendored copies and build scripts excluded.

FindingMedian repo
Share of 90-day line churn in the busiest 10% of files68%
Code health, whole repo7.1 out of 10
Code health, hotspot files only4.9 out of 10
Share of bug-fixed files that sit in the least-healthy 20% of files60%
Production files that nothing imports (flagged as unreachable)3.2%
Production files with a bus factor of 160%

Scroll the table sideways to see every column.

Three readings matter for a team. First, change is concentrated: in 150 of 186 repos (81%), half or more of all churn lands in 10% of files, so a debt budget spent on the whole codebase is mostly wasted. Second, the busiest files are the least healthy: in 174 of 186 repos (94%), hotspot files score below the repo average, by a median of 2.0 points. Third, low health points at real bugs: the 20 lowest-scoring files were bug-fixed 5.4 times as often as the average file in the median repo (173 repos with enough fix history). Dead code is common but not dominant: 89% of repos contain at least one unreachable production file, and these are engine findings, not verified deletions.

This is an association in history, not a forecast. The full method, definitions and per-language tables are in the state of open-source code health report.

How do you reduce technical debt once you can see it?

Pay down debt in the files you are already changing, in the order that frees the most future work. The practical order is: retire dead code first (no design needed), add tests to hotspots with no coverage (untested hotspots explains why this comes before refactoring), then split the complex, busy files. Keep each change small enough to review, since large pull requests hide regressions.

Put a limit on the work: a fixed share of each sprint, aimed at the top of the ranked list, beats a rewrite that needs permission.

FAQ

What is technical debt in simple terms?
Technical debt is the cost of choosing a quick or imperfect solution now, which makes later changes slower and riskier until it is fixed. Like financial debt it has a principal (the work to fix it) and interest (the extra effort each change costs while it remains).
What are examples of technical debt?
Common examples are a very long function that nobody dares edit, a module imported by half the codebase, an upgrade postponed for two major versions, a busy file with no tests, documentation that no longer matches the code, and a subsystem only one engineer understands.
How do you measure technical debt?
Combine complexity, churn, bug-fix history, dead code, duplication and ownership per file, and rank files where several signals overlap. Complexity multiplied by churn (a hotspot) is the strongest single view, because it shows where the debt is actually being paid.
Is technical debt always bad?
No. A deliberate shortcut taken to ship on time is a loan with a known repayment plan, and it can be the right call. The damaging kind is debt nobody knows about, or debt in code that changes every week and never gets repaid.
How much technical debt is normal?
Every codebase carries some. In our 195-repo dataset the median repo scored 7.1 out of 10 on code health, with hotspot files at 4.9, and 89% had at least one circular import group. The useful question is not how much debt exists but whether it sits in code that changes.
What is a technical debt ratio?
It is the estimated cost to fix the issues in a codebase divided by the estimated cost to build it, usually shown as a percentage. It is a trend indicator, and it does not say which files matter. Pair it with churn and bug history to decide what to fix.