Also called Tech debt, Code debt, Design debt
In depth How to prioritize technical debt: ranking debt by churn, bug history, reach and effort, with the commands to build the list.
How technical debt is measured
There is no single agreed unit. Three approaches are common:
| Approach | What it counts | Weakness |
|---|---|---|
| Debt ratio | Estimated remediation effort divided by the cost of developing the code (SonarQube maps 5% or less to an A rating) | Built from rule violations on one snapshot; the effort figures are estimates |
| Code metrics | Complexity, duplication, nesting, file size per file | Says how messy code is, not whether it hurts |
| History signals | How often a file changes, how many bug fixes it collects, how many people touch it | Needs git history; says nothing about code nobody changes |
Why the last row matters: two files both have a function with cyclomatic complexity 30. One changed 40 times last quarter and collected 6 bug fixes; the other has not changed in two years. Metrics give the size of the loan, change frequency the interest.
Why technical debt matters
The metaphor comes from Ward Cunningham's 1992 OOPSLA experience report on the WyCash portfolio system: shipping code that reflects an immature understanding is like taking a loan, fine if you repay it by refactoring, costly if you keep paying interest. Fowler's 2009 quadrant adds that debt is not always a mistake. Deliberate, prudent debt (ship now, repay next sprint) is a trade. Inadvertent debt is the kind teams discover later.
The consequence is speed: features in indebted code take longer and changes break things that look unrelated. The cost concentrates in the files that change often and many others import.
How to measure technical debt yourself
Free tools cover the inputs:
- Complexity per function:
radon cc -s -a src/(Python),lizard src/(many languages), ESLintcomplexity,gocyclo -over 10 .(Go). - Change frequency:
git log --since="90 days ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20. - An effort-based debt number tracked per pull request: SonarQube is the established choice.
Join the first two lists: complex, frequently changed files are debt with interest. SonarQube gives a tidier single figure but does not read git history.
How repowise measures technical debt
repowise scores every file from 1.0 to 10.0 for code health using 59 deterministic detectors, no LLM, and then ranks the files by what to fix first, with the first edit, an effort estimate and the tests to run for each item.
- Where you see it:
repowise healthon the CLI (top fix-first items, lowest-scoring files),repowise nextfor the cross-layer list, andget_healthover MCP. See the code health feature page. - History counts: churn, change entropy, ownership and prior bug-fix commits are inputs, so a messy file nobody changes ranks below a moderately messy file changed every week.
- Dead code first: unused code is debt you can delete instead of refactor; see dead code.
For the ranking method, read how to prioritize technical debt. For tool comparisons, see technical debt measurement tools compared.