Technical debt explained: when to take it, when to pay it off

Your CTO just said the codebase has “a lot of technical debt” and needs 3 months to clean it up before building new features. Your first instinct: they’re gold-plating. Your second instinct: maybe the code is actually falling apart. You don’t know which one is true because nobody explained what technical debt means in dollars.

Technical debt is not bad code. It’s not bugs. It’s not your developer being lazy. It’s the difference between the code you wrote to ship fast and the code you’d write if you had unlimited time. Every shortcut, every “we’ll fix this later,” every hardcoded value that should be configurable — that’s debt. And like financial debt, it charges interest.

The interest is paid in developer hours. A feature that should take 3 days takes 8 because the codebase fights back. A bug fix touches one file and breaks three others. New developers take 6 weeks to onboard instead of 2. That’s the compounding effect — and it’s why a $50,000 codebase can cost $30,000/year in debt servicing if nobody pays it down.

Good debt vs. bad debt

Not all technical debt is a mistake. Some of it is smart.

Strategic debt (good): You skip automated testing to ship your MVP 3 weeks faster. You hardcode the pricing page because you’ll change it 4 times in the next quarter anyway. You use a simpler database structure because you have 50 users, not 50,000. These are deliberate choices with known tradeoffs. You took the debt, you know it’s there, and you have a plan to pay it off.

Accidental debt (bad): The developer didn’t know a better approach existed. The architecture doesn’t support a feature you didn’t plan for. Nobody documented how the payment system works and now the original developer left. This debt is invisible until it causes a crisis.

Reckless debt (ugly): “We don’t have time for tests.” “Just copy-paste that function.” “We’ll refactor after launch.” Launch was 18 months ago. Nobody refactored. The codebase is a maze of duplicated logic, and every change is a gamble.

The distinction matters because the right response is different for each. Strategic debt gets a payoff sprint every 4-6 weeks. Accidental debt gets fixed when discovered. Reckless debt sometimes requires a partial rewrite.

What technical debt costs in real dollars

We audited a SaaS product last year — 18 months old, 4 developers, $320,000 total investment. The team was spending 35% of their sprint capacity on debt-related work: fixing cascading bugs, working around architectural limitations, and onboarding a new developer who couldn’t understand the existing code.

That’s $112,000 spent fighting the codebase instead of building features. The cleanup took 6 weeks and cost $28,000. After that, the team’s feature velocity doubled. They’d been paying 4x the cost of the fix — every year — in lost productivity.

The formula is simple: if your team spends more than 20% of their time on non-feature work (bug fixes, refactoring, workarounds, build issues), the debt is eating your runway. Below 15%, you’re in healthy territory.

When to take on debt deliberately

Speed matters more than perfection in three situations:

Pre-product-market-fit. If you’re still testing whether anyone wants your product, perfect code is wasted effort. Ship fast, validate, then invest in code quality for the features that proved valuable. Your MVP should be deliberately lean.

Competitive windows. A competitor launches a similar feature. You can ship yours in 2 weeks with shortcuts or 6 weeks without them. Take the debt. Ship. Refactor in the next sprint. The market won’t wait.

Throwaway prototypes. Building a proof of concept to test an idea? The code might get deleted entirely. Spending time on clean architecture for throwaway code is burning money.

The key: document what you skipped. A comment that says // TODO: replace hardcoded pricing with config takes 5 seconds and saves 5 hours of detective work later.

When to pay it off

Four signals that debt is overdue:

1. New features take 3x longer than they should. A feature that’s “simple” keeps hitting unexpected complications. That’s the debt blocking the path.

2. Bug fixes create new bugs. You fix something in the checkout flow and the notification system breaks. That’s tightly coupled code — a sign of accumulated shortcuts.

3. Developers avoid certain parts of the codebase. When your team says “don’t touch that file,” there’s a reason. That file is the most indebted code in your system.

4. Onboarding takes more than 2 weeks. A new developer should be productive in 1-2 weeks. If it takes 6 weeks, the code is undocumented, inconsistent, and fragile.

The payoff strategy

Don’t stop feature development to “clean up the code” for 3 months. That’s almost never the right call. Instead:

Dedicate 20% of each sprint to debt reduction. In a 2-week sprint, that’s 2 days. Enough to make steady progress without stalling the product roadmap. Over 6 months, that’s 24 developer-days of cleanup — enough to clear most high-interest debt.

Prioritize by pain. Fix the debt that slows down the features you’re building next. Don’t refactor the billing system if your next 3 sprints are all about the reporting dashboard.

Combine with feature work. Need to add a new payment method? That’s the perfect time to refactor the payment module. The feature justifies the sprint allocation. The refactoring reduces future debt.

The software development life cycle doesn’t have a “debt phase” because debt management is continuous. Budget for it like you budget for maintenance costs — 15-20% of your annual development spend.

---

Suspecting your codebase is carrying expensive debt? Send us access and we’ll tell you exactly where the debt is, what it costs, and what to fix first. Get an audit.