Glossary
Technical debt tracking quantifies code messiness - test coverage, complexity, change failure rates, and coupling - making invisible velocity drains visible so product teams can prioritize debt paydown as a business problem, not just a code quality issue.
At Salesken, we had a 'tech debt' label in Jira with 200+ tickets. When our board asked how much technical debt we had, I couldn't give them a number. That experience taught me that unmeasured debt is invisible debt.
Technical debt tracking is the ongoing monitoring of technical debt in a codebase. It answers: What technical debt do we have? Is it getting better or worse? Which systems are deteriorating? What's the trend?
Tracking involves: measuring key metrics (test coverage, code complexity, error rates), establishing baselines, monitoring over time, and periodically reassessing.
The goal: make technical debt visible so decisions about paying it down are informed by data.
Without tracking, technical debt is invisible. You might notice it gets harder to ship features, but you don't know why. Is the codebase getting more complex? Is test coverage declining? Are error rates increasing? Without tracking, it's just a feeling.
Tracking makes it concrete. "Test coverage declined from 45% to 35% over the past year." "Error rates in the payment module increased 20%." "This system's cyclomatic complexity increased 15%." These are facts you can present to leadership and make decisions about.
Tracking also helps you know if your debt paydown efforts are working. "We spent 3 months refactoring the payment module. Did test coverage improve?" Tracking answers that question.
Test coverage: Percentage of code tested. Track overall and by system. Declining coverage is a warning sign.
Code complexity: Cyclomatic complexity or similar metric. Increasing complexity makes code harder to change.
Code duplication: Percentage of code that's duplicated. Duplication makes maintenance harder.
Error rates: How often systems fail. Increasing error rates suggest problems.
Bugs: Bugs found per sprint or per release. Increasing bugs suggest code quality issues.
Velocity: How many points completed per sprint. Declining velocity suggests technical debt burden increasing.
Cycle time: How long does it take to ship a feature? Increasing cycle time suggests technical debt slowing you down.
System-level health: For each major system: complexity, coverage, error rate. Identify hot spots.
1. Choose metrics. Don't track everything. Track 3-5 metrics that matter most to your business.
2. Establish baselines. What's the current state? "Our overall test coverage is 35%." That's the baseline.
3. Set goals. "We want to reach 60% test coverage in the next year." Goals give direction.
4. Measure regularly. Monthly or quarterly. Automate where possible (test coverage tools can run automatically).
5. Visualize trends. Graphs are powerful. Seeing test coverage declining from 45% to 35% over a year is more impactful than a data table.
6. Act on data. If test coverage is declining, why? Discuss with the team. Is it because you're shipping faster (less time for tests)? Is it because you're not investing in tests? Either way, decide: do we care? What will we do?
Automated: Code complexity, test coverage, code duplication. Tools measure these automatically. Easy to track over time. You can set up continuous measurement (every commit).
Manual: Cycle time, velocity, team perception of pain points. Requires asking the team. Harder to automate, but valuable insight.
Best approach: Combine both. Automated metrics give objective data. Manual assessment gives context.
"Measuring everything." Measurement takes effort. Measure what matters for decisions you're making. Don't collect data you won't act on.
"Treating metrics as absolute truth." Metrics are imperfect. Test coverage can be high and still have bugs (if tests are weak). Error rates can appear low if monitoring is incomplete. Use metrics as signals, not gospel.
"Tracking without acting." If you measure but don't act, measurement is useless. Every month you measure test coverage declining, but you don't allocate time to improve it. That's waste. Either stop measuring or act.
"Setting unrealistic improvement goals." "We're at 20% test coverage, let's hit 100% in 6 months." Unrealistic. You'll either not hit the goal or burn out trying. Set realistic goals. "Improve 10% per year." That's better.
"Not accounting for context." If error rates went up but you shipped 3x more features, increased error rate might be normal. Context matters. Track alongside other metrics.
Code metrics: SonarQube, CodeClimate, Codacy. These measure complexity, coverage, duplication.
Error monitoring: New Relic, Sentry, DataDog. These track errors in production.
Velocity/cycle time: Jira, Linear. Built into project management tools.
Dashboards: Grafana, Metabase. Build custom dashboards for metrics you care about.
You don't need expensive tools to start. Open-source tools work fine. The important thing: track something, not necessarily tracking everything.
Hard data is more persuasive than anecdotes:
Instead of: "The code is getting messier."
Say: "Code complexity increased 20% in the last 6 months. At this rate, iteration time will increase 30% within a year, slowing our shipping velocity."
Instead of: "We should improve test coverage."
Say: "Our test coverage is 35%. Industry benchmark is 60%. Our error rate is 2x average. If we invest in tests, we project error rates to drop 50%."
Data drives decisions better than opinions.
Stable systems: If a system hasn't changed in 2 years and works fine, you don't need to track its metrics. Tracking is for active, changing systems.
Metrics you won't act on: If you won't change decisions based on a metric, don't track it. Tracking is for decision-making.
Too early: If you're 6 months into a project, extensive technical debt tracking might be premature. Wait until there's actual history.
Q: How often should we track technical debt?
A: Depends on pace of change. Fast-moving teams: monthly. Slower teams: quarterly. At minimum, quarterly.
Q: Should we share debt metrics with leadership?
A: Yes, in business terms. "Test coverage affects error rates, which affects customer satisfaction and support costs. Here's our coverage trend." Leadership needs visibility.
Q: What if we're below industry benchmarks?
A: Context matters. Maybe your product is simpler (benchmarks don't apply). Maybe you're earlier-stage (debt accumulates over time). Decide: is this a problem worth fixing? If yes, set a goal and track progress.
Q: How do we prevent regression?
A: Set minimum standards. "We won't merge code that reduces test coverage." Enforce with tooling (code review gates). Track over time.
Keep reading
Related resources
