A client came to us last year with a simple request: add a referral feature to their marketplace app. Two weeks of work, they assumed. Our estimate was eleven.
The difference was not the referral feature. It was that their user model had been patched six times to accommodate new account types, each patch adding a conditional rather than a proper abstraction. Touching user records meant touching 40 files. That gap — between what a change should cost and what it does cost — is technical debt in software, and it is the single most common reason a roadmap quietly stops moving.
What technical debt in software actually means
Technical debt is the accumulated cost of shortcuts taken in a codebase. Like financial debt, it has a principal (the shortcut itself) and interest (the extra time every future change takes because the shortcut is there).
The metaphor matters because it reframes the conversation. Debt is not automatically bad. Borrowing to reach a market window can be the correct business decision. What kills companies is unmanaged debt — borrowing without tracking the balance, and being surprised when the interest payments consume the entire development budget.
Not all debt is the same
Deliberate debt is a conscious trade: we will hardcode the pricing tiers now to ship for the trade show, and refactor in Q2. Written down, scheduled, revisited. This is healthy.
Accidental debt comes from a design that made sense at the time and stopped making sense as the product grew. Nobody did anything wrong. The product outgrew its architecture.
Bit rot is debt accumulated by standing still — dependencies going out of support, security patches deferred, a framework three major versions behind. You did not take a shortcut; the world moved.
Negligent debt is the dangerous category: no tests, no documentation, no review process, copy-pasted logic. This is not a trade-off, it is just damage, and it compounds fastest.
The warning signs you can spot without reading code
You do not need to be technical to diagnose a debt problem. The symptoms show up in your calendar and your budget.
Estimates keep growing for similar work. A feature comparable to one built last year now quotes at triple the time. Nothing about the feature changed; the ground underneath it did.
Every release breaks something unrelated. You ship a change to checkout and the email notifications stop working. This is the signature of tight coupling — parts of the system that should be independent are not.
The team keeps saying “we need to be careful with that part.” There is a module everyone avoids. It was written by someone who left. Nobody fully understands it, so changes near it get padded with caution.
Onboarding a new developer takes months. A healthy codebase gets a competent new hire productive in two to three weeks. If it takes three months, the system’s complexity is undocumented and lives in people’s heads.
Bug fixes create new bugs. Your defect count is flat or rising despite steady fixing. That is a sign fixes are being applied to symptoms rather than causes.
Deployments are events. If releasing requires a planned evening, a checklist, and someone on standby, you have deployment debt. Mature teams release during the working day without ceremony.
How to measure it
Vague anxiety about code quality does not win budget. Numbers do.
| Metric | What it tells you | Rough healthy range |
|---|---|---|
| Change failure rate | % of releases causing an incident | Under 15% |
| Lead time for a small change | Idea to production for a one-day task | Under a week |
| Test coverage on core paths | How much of the critical logic is protected | 70%+ on business logic |
| Defect escape rate | Bugs found by users vs by testing | Under 20% |
| Dependency currency | Libraries more than one major version behind | Under 10% |
| Code churn in a single area | Files repeatedly rewritten | Flag anything rewritten 5+ times a year |
Most of these can be pulled from your version control and issue tracker without a consultant. Run them quarterly and you get a trend line, which is more useful than any single reading.
What it costs to ignore
The costs show up in four places.
Velocity decay. Teams carrying heavy debt commonly lose 30–40% of their capacity to working around the codebase rather than extending it. You are paying a full team and receiving two-thirds of a team.
Hiring and retention. Good engineers leave codebases they cannot do good work in. Replacement cost for a mid-level developer runs six months of salary once you count recruitment, notice periods and ramp-up.
Security exposure. Out-of-date dependencies are the most common breach vector in web applications. Debt in your dependency tree is not an engineering inconvenience; it is a compliance and insurance problem.
Strategic paralysis. The worst outcome is that your roadmap starts being written by your architecture. Opportunities get declined because “we cannot do that with the current system.” At that point the debt is making business decisions for you.
Our guide on how to future-proof a software investment covers the preventative side of this in more depth.
When to pay it down — and when not to
Not all debt is worth repaying. Apply three tests.
Is the code changing? Debt in a module nobody has touched in three years costs nothing. Ugly, stable code that works is not a problem. Prioritise debt in areas with high change frequency.
Does it block something on the roadmap? Refactoring for elegance is a hobby. Refactoring because it unblocks the three features you committed to next quarter is a business case.
Is the product’s life longer than the payback period? Do not refactor a system you plan to replace in eighteen months. Debt on a dying asset should be left exactly where it is.
Three approaches that work
The boy scout rule. Every time a developer touches a file, they leave it slightly better. No separate budget, no project. Slow, but it compounds and never needs approval.
The 20% allocation. One day in five, or roughly 20% of each sprint, reserved for debt work. The team chooses the targets. This is the approach we recommend to most clients because it is predictable to budget and it stops debt from accumulating faster than it is repaid.
The strangler pattern for big rewrites. When a module genuinely needs replacing, build the new version alongside the old one and migrate traffic piece by piece, rather than attempting a big-bang rewrite. Full rewrites have a poor completion record — they take longer than estimated, deliver no new features during the rebuild, and frequently reproduce the original problems.
Avoid the fourth approach, which is the most commonly chosen: wait until it becomes a crisis, then request a large one-off refactoring budget. By then the cost is at its highest and your negotiating position at its weakest. This is also what inflates a realistic development timeline on every subsequent project.
Talking to your board about it
Technical debt loses budget arguments because it is pitched as a technical concern. Reframe it.
Not: “The codebase needs refactoring.”
But: “Features in the orders module currently take 2.5x longer to build than equivalent features elsewhere. Four of our next six roadmap items are in that module. Eight weeks of structural work now returns roughly fourteen weeks of capacity over the following year.”
Attach the metric, attach the roadmap impact, attach the payback period. Debt work funded that way gets approved. Debt work pitched as cleanliness does not.
Frequently asked questions
Is technical debt always bad?
No. Deliberate, documented, scheduled debt is a legitimate way to reach a deadline. The problem is debt nobody is tracking.
How much technical debt is normal?
Every production codebase has some. A useful benchmark: if more than 25–30% of your development time goes to working around existing code rather than building, you are above a sustainable level.
Should we rewrite from scratch?
Almost never as a first option. Incremental replacement via the strangler pattern carries far less delivery risk. Consider a full rewrite only when the platform itself is end-of-life or the business model has fundamentally changed.
Can an outside team assess our technical debt?
Yes — a code and architecture audit typically takes one to two weeks and produces a prioritised remediation plan with effort estimates. It is worth doing before any major investment decision or acquisition.
Not sure whether your velocity problem is debt or process? Book a 30-minute consultation — we will look at your repo metrics and tell you which one it is.




