Choose technical debt metrics that connect workarounds, change lead time, incidents, code hotspots and dependency age to review and remediation decisions.
For two years, I tracked technical debt using SonarQube's "technical debt ratio." Every month I'd present the number to leadership. Every month they'd nod politely and move on. The metric meant nothing to them because it meant almost nothing to me either.
Then I switched to metrics that connected directly to outcomes people cared about: shipping speed, incident frequency, and engineering retention. Everything changed.
Here's the thing most articles about tech debt metrics get wrong: they treat measurement as an end in itself. A number on a dashboard doesn't reduce debt. A metric only matters if it changes behavior. Every metric below has a suggested action trigger attached to it. Use the technical debt guide to interpret it in the context of the work.
Let me save you some time. These metrics sound good in blog posts but fail in practice:
Lines of code. More code isn't necessarily more debt. A 500-line file with clear abstractions beats a 100-line file with three responsibilities crammed together.
SonarQube debt ratio in isolation. It compares estimated remediation effort for maintainability issues with an estimated development cost. Use it as one input to the decision.[1]
I've seen codebases with an "A" rating that were miserable to work in because the architecture was broken, not the syntax.
Code coverage percentage. 90% coverage with bad tests is worse than 60% coverage with good tests. Coverage measures quantity of testing, not quality.
Cyclomatic complexity averages. Averaging complexity across a codebase hides the hotspots. A codebase with an average complexity of 5 might have one module at 45 that causes all the pain.
This is my single most important metric. It measures how much slower your team is compared to what they could be.
Velocity Delta = (Time on Feature Work) / (Time on Feature Work + Time Fighting Debt)
Track it weekly by asking developers a simple question in standup or async: "How many hours this week did you spend on work that would have been unnecessary if the codebase were in better shape?"
This includes time spent:
Working around known issues
Debugging failures caused by brittle code
Manually testing because automated tests are unreliable
Waiting for slow builds or deploys
Onboarding struggles due to unclear code
Action trigger: When velocity delta drops below 70% (meaning 30%+ of engineering time is debt-related), you have a business case for dedicated remediation.
The command below counts file appearances in non-merge commit history. Combine that change-frequency signal with complexity when selecting code to investigate.[2]
bash
# Count file appearances in non-merge commits over the last 6 monthsgit log --since="6 months ago" --no-merges --name-only --pretty=format: | \ sed '/^$/d' | sort | uniq -c | sort -rn | head -20
Cross-reference this with complexity (measured via your static analysis tool), as described in the hotspot analysis guide. Files that are both complex AND frequently changed are your top priorities.
File
Changes (6mo)
Complexity
Priority
src/payments/processor.ts
47
High
CRITICAL
src/auth/session.ts
38
High
CRITICAL
src/api/routes.ts
52
Medium
HIGH
src/utils/helpers.ts
31
Low
MEDIUM
src/db/migrations.ts
28
Low
LOW
Action trigger: Any file with >30 changes in 6 months AND high complexity gets added to the debt register immediately.
How long does it take from "start working on a change" to "change is in production," broken down by area of the codebase? This is a local work-start measure. DORA change lead time starts at the version-control commit, so keep the definitions distinct.[3]
typescript
interface ModuleLeadTime { module: string; avgLeadTimeHours: number; p95LeadTimeHours: number; baselineHours: number; // what it should take overhead: number; // avgLeadTime - baseline}// Real numbers from a project:const modules: ModuleLeadTime[] = [ { module: "user-profile", avgLeadTimeHours: 8, p95LeadTimeHours: 16, baselineHours: 6, overhead: 2 }, { module: "payments", avgLeadTimeHours: 34, p95LeadTimeHours: 72, baselineHours: 8, overhead: 26 }, { module: "notifications", avgLeadTimeHours: 12, p95LeadTimeHours: 24, baselineHours: 6, overhead: 6 },];// payments module: 26 hours of overhead per change. That's the cost of debt.
Action trigger: Any module where average lead time is >3x baseline gets a root cause analysis within two weeks. A debt business case can then make the proposed investment explicit.
Which parts of your system cause the most production incidents per change?
Incident Density = Incidents / Deployments (per component)
This ratio counts incidents per deployment. A value of 0.25 means one incident per four deployments on average, which is not necessarily the percentage of deployments that failed because incidents can share a deployment or have other causes.
Action trigger: Incident density >0.15 triggers mandatory remediation planning. Above 0.3, freeze non-critical changes to that component until the root cause is fixed.
Track this as a trend line, not a point-in-time number. Build time creep is one of the most reliable early indicators of accumulating debt.
Week 1: CI Pipeline: 12 min
Week 8: CI Pipeline: 18 min
Week 16: CI Pipeline: 27 min
Week 24: CI Pipeline: 41 min <-- you waited too long
Every minute added to your CI pipeline is multiplied by the number of developers and the number of daily pushes. A 10-minute increase with 15 developers pushing 3 times a day costs 7.5 hours of wait time daily.
Action trigger: >15% increase in CI time over any 8-week period triggers investigation.
How long does it take a new engineer to ship their first meaningful PR? Track this for every new hire.
If your onboarding time is increasing, your codebase is getting harder to understand. That's debt.
Hire
Start Date
First Meaningful PR
Days
Engineer A
Jan 2025
Jan 12, 2025
8
Engineer B
Apr 2025
Apr 22, 2025
15
Engineer C
Aug 2025
Sep 5, 2025
21
Engineer D
Jan 2026
Jan 29, 2026
20
That trend (8, 15, 21, 20 days) warrants investigation. Compare task scope, experience and onboarding support before attributing the change to codebase quality.
Action trigger: When onboarding time exceeds 2 weeks consistently, invest in documentation, code simplification, or both.
interface DependencyHealth { name: string; currentVersion: string; latestVersion: string; majorVersionsBehind: number; lastUpdated: string; hasKnownVulnerabilities: boolean; riskScore: number; // non-negative sum; the weights below are not capped}// Risk scoring:// 1 major version behind = 2 points// Each additional major = 3 points// Known vulnerability = 5 points// Last updated >2 years ago = 3 points
I was wrong about this metric for a long time. I used to think minor version updates didn't matter. Then a transitive dependency three levels deep had a critical CVE, and the fix required updating through two major versions of a direct dependency. We spent a week on what should have been a 1-hour security patch.
Action trigger: Any dependency with a risk score >7 gets scheduled for update within 30 days.
DORA recommends recording dependency versions and how often libraries are upgraded. The score and deadline above are proposed local review rules.[4]
Most teams measure too much and act too little. I'd rather have one metric tracked religiously with clear action triggers than a dashboard of 20 metrics that nobody looks at.
If you only track one thing, track Developer Velocity Delta. When engineers are spending 30% of their time fighting the codebase instead of building features, the business case writes itself. Everything else is supporting evidence.
Stop collecting data. Start making decisions.
Frequently asked questions
Is a technical debt ratio enough to prioritise work?
A static-analysis debt ratio describes a tool-defined set of maintainability issues and estimated remediation effort. Combine it with the work the team actually performs and the failures it encounters before choosing a remediation priority.
Does incident density equal the percentage of failed deployments?
Incidents divided by deployments is a count ratio. It equals the share of deployments that failed only when each counted incident maps to one distinct deployment under the same definition and time window, so record those relationships explicitly.
What does the Git churn command in this article count?
The example counts appearances of file paths in the selected commit history. It is a change-frequency signal, rather than a count of lines added or removed, and should be interpreted with the project's merge and rename history in mind.
Are the action thresholds industry benchmarks?
The article's cutoffs are suggested starting points for discussion. Calibrate them to your application, workload and observation period, and inspect the underlying cause before treating a threshold breach as evidence that debt caused the result.
Most code quality dashboards fail because they track too many metrics and live outside the team's workflow. Here are exactly 7 metrics and a 3-week adoption plan that actually works.
Small frictions cost more than big blockers. 47 micro-frictions consume 96 minutes per engineer per day. Here's the TAX Return framework for finding and eliminating the developer productivity tax.
Compare cyclomatic and cognitive code complexity with change risk. Check corrected examples, understand each measure’s limits and target refactoring effort.
Engineers spend 38% of their time on repetitive, automatable work. Here's a toil audit process that identifies where time disappears and a framework for systematic elimination with measurable ROI.
Developer experience is a systems design problem, not a culture problem. Platform engineering reduces cognitive load from 12 concepts to 3 for common tasks. Here's the LOAD assessment framework.
Code churn reveals more about team health than any code quality score. Learn to distinguish healthy churn from warning signs using the CHURN framework.