On this page
- What is technical debt?
- What are the types of technical debt?
- How do you measure technical debt?
- Step 1: find where work happens (churn)
- Step 2: find what is hard to change (complexity)
- Step 3: cross the two
- Step 4: check the cost already paid (bug fixes)
- Step 5: add dead code, duplication and ownership
- Doing all of it in one pass with repowise
- What about a technical debt ratio?
- What does technical debt look like in real codebases?
- How do you reduce technical debt once you can see it?
- FAQ
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.
| Kind | Example | How it shows up |
|---|---|---|
| Code debt | A 600-line function with nested conditions | High complexity, slow reviews, bugs on every edit |
| Design debt | A module that every other module imports | One file in the middle of every change, wide blast radius |
| Dependency debt | An unmaintained library, a framework two majors behind | Blocked upgrades, unpatched advisories |
| Test debt | A hot file with no tests | Fear of changing it, regressions that tests would catch |
| Documentation debt | A README that describes last year's architecture | Slow onboarding, wrong answers from people and agents |
| Dead code | Unused files, exports and packages | Noise in search, false confidence in what is in use |
| Knowledge debt | A subsystem only one engineer has touched | A bus factor of 1, stalled work when they are away |
| Infrastructure debt | Hand-run deploys, flaky CI | Releases 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.
| Signal | What it tells you | Command or tool |
|---|---|---|
| Complexity | Where code is hard to change | lizard, radon, gocyclo, SonarQube cognitive complexity |
| Churn | Where work actually happens | git log --name-only (below) |
| Churn times complexity | Where debt charges interest | Hotspot analysis |
| Bug-fix history | Where the debt already caused defects | Commits matching fix, linked issues |
| Dead code | Code that costs reading time and does nothing | Knip, vulture, deadcode |
| Duplication | Fixes that must be made in several places | jscpd |
| Ownership | Where knowledge is thin | git 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:
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:
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:
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:
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.
| Finding | Median repo |
|---|---|
| Share of 90-day line churn in the busiest 10% of files | 68% |
| Code health, whole repo | 7.1 out of 10 |
| Code health, hotspot files only | 4.9 out of 10 |
| Share of bug-fixed files that sit in the least-healthy 20% of files | 60% |
| Production files that nothing imports (flagged as unreachable) | 3.2% |
| Production files with a bus factor of 1 | 60% |
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.



