Glossary
By Glue Team
Technical debt assessment is the process of identifying, measuring, and quantifying the cost of shortcuts, legacy code, and architectural compromises in your codebase. Like financial debt, technical debt incurs interest: every day you delay addressing it, engineering velocity slows and bugs multiply.
Honest assessment is uncomfortable. It reveals:
Yet most teams avoid assessment. They guess: "We probably have about 20% tech debt." Reality is usually 40-60%.
Code debt: Legacy modules that are hard to change, outdated dependencies, spaghetti code with unclear responsibility.
Architecture debt: Services that should be split but are monolithic, missing abstraction layers, tight coupling between components.
Test debt: Low coverage, flaky tests, absence of integration tests, manual testing for features that could be automated.
Documentation debt: No runbooks, missing design docs, tribal knowledge that leaves when key engineers do.
Process debt: Deployment is slow, manual, error-prone; no automated quality checks; incident response is chaotic.
Quantify the cost: Track hours spent refactoring, fixing bugs in legacy code, waiting for slow builds, and on-call incidents. Multiply by average engineer cost. This is your annual tech debt tax.
Map debt location: Which modules cause the most incidents? Which have lowest test coverage? Which require 3x longer to modify? Prioritize the painful ones.
Measure complexity: Use code metrics to identify high-complexity, high-churn code—the combination signals debt.
Survey engineers: Anonymous survey asking "Which parts of the codebase slow you down?" reveals what metrics might miss.
Estimate remediation cost: For high-priority debt, estimate effort to fix. A module might cost 3 sprints to refactor and save 100 hours/year; ROI is clear.
The mistake: "We have too much tech debt and need to refactor."
The win: "Tech debt costs us $400K/year in lost engineering productivity. Refactoring the payment module will save 200 hours/year. Let's prioritize that in Q2."
When debt is quantified in business terms, leadership funds it.
Q: How much technical debt is acceptable? A: A healthy codebase allocates 20-30% of engineering capacity to debt reduction/refactoring. If you're doing less, debt compounds. More than 50% and you're paying too much interest.
Q: Should we schedule "tech debt sprints" or integrate refactoring into regular sprints? A: Both. Regular sprints include 20-30% refactoring within features. Dedicated sprints tackle isolated problems. Alternating both approaches prevents debt from spiking.
Q: How do we get engineers to care about tech debt? A: Show impact: "This refactoring saves you 5 hours/week in build time." Self-interest works better than moral arguments.
Keep reading
