Every engineering team has a version of the same conversation. A feature that should take two days takes two weeks. Nobody can explain exactly why, but everyone points vaguely at the same part of the codebase and says something like “that area is a mess.”
That mess has a name, and the name is doing a lot of damage. Calling it technical debt makes it sound like a financial instrument with a repayment schedule, which encourages executives to treat it as optional and engineers to treat it as an excuse. Neither is right.
What follows is an attempt to be concrete: what technical debt actually costs, how to make that cost visible to people who do not read code, which debt is worth carrying, and how to pay down the rest without stopping the business for a rewrite that will not survive contact with reality.
The Metaphor Is Half Wrong
The original idea behind the term was reasonable. You ship something imperfect to learn faster, and you accept that you will pay interest until you clean it up. That is a deliberate trade with a known cost, and it is often the right call.
The problem is that most of what teams call technical debt was never a decision. Nobody sat down and chose to leave the authentication logic duplicated across four services. It happened through turnover, deadline pressure, changing requirements, and a hundred small choices that each made sense in isolation.
The other flaw in the metaphor is the interest rate. Financial debt has a known, fixed cost you can plan around. Technical debt has a variable rate that depends entirely on where the code sits and what you do next. Ugly code in a module nobody touches costs approximately nothing. Ugly code in the path of every new feature compounds viciously.
The cost of technical debt is not a property of the code; it is a property of the code multiplied by how often you have to go near it.
This single reframe changes prioritization more than any tooling. Stop asking “what is the worst code in our system” and start asking “what code is both bad and directly in the way of what we plan to build next quarter.”
Where the Money Actually Goes
The cost of debt rarely appears as a line item. It surfaces in ways that get attributed to other things.
Feature Velocity Decay
The most visible symptom. Work that would have taken three days at the start of the product takes three weeks two years in. The team has not gotten worse. The system has gotten harder to change safely.
This is the cost that shows up in roadmap conversations as “engineering is slow.” It is usually not slowness. It is the tax of understanding the existing behavior, finding every place a change ripples, and testing manually because the automated coverage is thin.
The Fear Tax
A quieter and often larger cost. When engineers are afraid to touch something, they route around it. New logic gets bolted on beside the old logic rather than replacing it. Special cases accumulate. The system grows a second, parallel way of doing something because the first way is too frightening to modify.
Over time this produces a codebase where the same concept is implemented three different ways, and nobody is sure which one is authoritative. Every subsequent change has to account for all three.
Incident Load
Systems with heavy debt break more often and take longer to fix. Debugging a well-structured system means narrowing down to one place. Debugging a tangled one means holding a lot of unrelated context in your head while under time pressure at an inconvenient hour.
The cost is not only the outage. It is the engineering hours consumed, the follow-up work, the customer trust, and the effect on people who get paged repeatedly for the same underlying cause.
Onboarding Drag
How long does it take a new engineer to ship something meaningful? In a clean system, days. In a heavily indebted one, months — and a meaningful share of them will leave before they get there, because the experience of being permanently confused is demoralizing.
This cost is almost never attributed to technical debt. It gets logged as recruiting difficulty or a hiring mistake.
Optionality Loss
The largest cost and the hardest to see, because it is measured in things that did not happen. A competitor ships an integration you cannot match in a reasonable timeframe. A large customer asks for a capability your data model cannot express. A pricing change that should be a configuration update turns into a quarter of work, so you do not make it.
The business never sees this as a technical problem. It sees a market it could not move into quickly, and it looks for a strategic explanation.
Not All Debt Deserves Repayment
The instinct to clean everything is expensive and usually wrong. Some debt should be left alone, permanently.
- Debt in stable, isolated code. A component written badly four years ago that has not needed a change since and has no upcoming work is costing nothing. Refactoring it is an expense with no return.
- Debt in code scheduled for removal. If a system is being replaced next quarter, improving it is throwing money at something with a short remaining life.
- Debt that is merely unfashionable. Code written in an older style, or with a framework that is no longer trendy, is not automatically debt. If it works, is understood, and is not blocking anything, “we would write it differently now” is not a business case.
Conversely, some debt should be treated as urgent even without a feature request attached — anything that creates a security exposure, silently corrupts data, or makes an outage significantly more likely. Those carry a tail risk that does not show up in velocity metrics until it shows up all at once.
A Simple Prioritization Frame
For each candidate area, ask three questions and be honest about the answers:
- How often does anyone need to change this? Version control tells you. Files with high change frequency and high complexity are where the compounding happens.
- What does it block? Not hypothetically — on the actual roadmap for the next two or three quarters. If nothing planned goes through it, the interest rate is near zero.
- What is the failure mode if we ignore it? Slow feature work is one answer. Data loss is another. They deserve very different urgency.
Anything scoring high on all three is worth real investment. Anything scoring low on all three should be documented and left alone. The middle is a judgment call, and the honest thing to do is make it explicitly rather than by drift.
Making the Cost Visible to People Who Do Not Code
Most engineering teams lose this argument because they make it in engineering terms. “The service layer has poor separation of concerns” describes a technical state, not a business consequence, and it lands as a preference.
The translation that works has three parts: a specific business capability, a time cost, and a comparison.
Weak version: “We need to refactor the billing module; it has grown unmaintainable.”
Strong version: “Three of the four pricing changes on this year’s roadmap route through the billing module. At current structure, each takes about six weeks. Two weeks of restructuring work first would bring each of those to roughly two weeks. That is a net saving of about ten weeks across the year, and it removes the main source of billing incidents.”
The numbers are estimates and everyone knows it. The point is that the conversation is now about trade-offs on a shared timeline rather than about code quality as an aesthetic value. Business leaders are generally good at evaluating that kind of trade. They are bad at evaluating claims of architectural purity, and rightly suspicious of them.
Track Something, Even If It Is Rough
You do not need sophisticated metrics. A few crude signals, tracked consistently, are enough to show direction:
- Time from starting a typical feature to shipping it, tracked over quarters.
- The proportion of engineering time spent on unplanned work — incidents, bugs, emergency fixes.
- Change failure rate: how often does a deploy require a follow-up fix.
- Time for a new hire to merge their first meaningful change.
Any of these getting worse over several quarters is evidence that maintenance is losing to feature pressure. Presented as a trend, it is far more persuasive than any individual complaint about a specific file.
How to Actually Pay It Down
The two common approaches both fail, in opposite ways.
The first is the big rewrite. A team declares the system unsalvageable and starts fresh. The rewrite takes far longer than estimated, the old system still needs maintenance during the transition, business requirements change midway, and the new system accumulates its own shortcuts under deadline pressure. A meaningful share of rewrites are abandoned partway, leaving two half-systems where there was one whole one.
The second is the perpetual “we will clean it up later.” Later never arrives, because there is always a more urgent feature, and the debt compounds until velocity collapses badly enough to force a crisis.
What works sits between them.
Improve What You Touch
The most reliable pattern is opportunistic. When you work in an area, leave it better than you found it — modestly, within the scope of the change. Extract the tangled function you had to understand. Add tests around the behavior you just modified. Delete the dead branch you confirmed is unreachable.
This works because it naturally concentrates effort where change frequency is highest, which is exactly where debt compounds fastest. It requires no separate budget and no roadmap negotiation. It requires a team norm that a change of this size is expected and not treated as scope creep.
Strangle, Do Not Replace
For genuinely bad subsystems that need replacing, build the new implementation alongside the old one and migrate traffic incrementally. Route a small percentage first, compare behavior, expand, and remove the old path only when nothing depends on it.
It is slower than a clean rewrite in theory and much faster in practice, because you are never in a state where nothing works. You can stop halfway and still have delivered value, which is the property big rewrites lack entirely.
Fund It Explicitly
Opportunistic improvement handles the everyday accumulation. Structural problems — a wrong data model, a missing abstraction that forces duplication everywhere, an architectural decision that no longer fits — need dedicated work with a defined scope and outcome.
Treat these like features. Give them a name, a rationale, an estimate, and a definition of done. “Reduce the checkout flow’s dependency on the legacy inventory service so that pricing changes no longer require coordinated deploys” is a project a business can evaluate. “Refactor the checkout code” is not.
Frequently Asked Questions
What percentage of engineering time should go to technical debt?
There is no universal number, and any figure quoted as a rule is arbitrary. The useful approach is to look at where the pain is: if unplanned work is consuming a large and growing share of the team’s time, that is the signal to invest more, regardless of what proportion any framework suggests. A young product exploring product-market fit should carry more debt deliberately. A mature product with many customers should carry less.
How do we stop new debt from accumulating as fast as we pay it down?
Most new debt comes from three sources: unclear requirements that lead to guessed abstractions, deadline pressure with no follow-up, and inconsistent standards across a team. The countermeasures are correspondingly practical — clarify requirements before designing, write down shortcuts you knowingly take at the moment you take them, and make code review a real quality gate rather than a formality. Debt taken deliberately and recorded is manageable. Debt that accumulates invisibly is not.
Is it worth fixing debt in a product we might sunset?
Generally no, with one exception. If the product is genuinely on a path to retirement, spend nothing beyond keeping it secure and stable. The exception is when the debt is causing incidents that consume the team’s attention or damage customer relationships that extend beyond that product. In that case you are not investing in the product, you are buying back focus.
The Underlying Discipline
The teams that stay fast over years are not the ones with the cleanest code. They are the ones that keep an accurate picture of where their system is fragile and make deliberate choices about it.
Debt itself is not the failure. Shipping something imperfect to learn faster is often exactly right, and a team with no technical debt has probably been too careful to move quickly. The failure is losing track — taking shortcuts without recording them, letting the map of what is fragile live only in the heads of people who may leave, and discovering the accumulated cost only when a routine request turns out to be impossible.
The practical habit is small and unglamorous. When you take a shortcut, write down what you skipped and what would need to be true to fix it. When you notice something rotten, note it rather than either fixing it immediately or forgetting it. Review that list when planning, and be willing to decide that some entries stay unfixed forever.
That is the entire discipline: know what you owe, know what it costs, and choose. Most teams that end up in a crisis did not make bad choices. They stopped making choices at all, and let the accumulation happen on its own.
