Managing Technical Debt: A Practical Framework

What Counts as Debt

"Technical debt" gets thrown around loosely. Not everything ugly is debt.

Actual technical debt:

• Shortcuts taken knowingly to hit a deadline
• Code that was fine when written but doesn't fit anymore
• Dependencies that haven't been updated in years
• Missing tests for critical paths
• Workarounds that became permanent

Not really debt, just messy code:

• Inconsistent naming conventions
• Code you personally don't like
• Old patterns that still work fine
• "Not how I would have done it"

The difference matters. Debt has a real cost—it slows down future work. Messy code that doesn't slow anyone down isn't debt worth addressing.

---

Measuring the Impact

Before deciding what to fix, understand what it's costing you.

Developer time: How much longer do features take because of this code? If a 2-hour task becomes a 2-day task, that's measurable.

Bug rate: Are bugs concentrated in certain areas? High-bug code is high-debt code.

Onboarding time: How long before new developers can work in this area? Weeks of onboarding represents a real cost.

Change frequency: Code you never touch doesn't matter. Code you touch every sprint matters a lot.

Build a simple table:

This tells you where to focus.

---

Prioritization Framework

Not all debt needs fixing. Some should be left alone.

Fix now: High impact + touched frequently

These areas slow your team down every sprint. Fixing them has immediate payoff.

Plan for it: High impact + touched rarely

Important but not urgent. Put it on the roadmap when there's a natural opportunity (like when you need to add a feature there anyway).

Maybe someday: Low impact + touched frequently

Annoying but not actually slowing anyone down much. Low priority.

Leave it alone: Low impact + touched rarely

Don't waste time on code that isn't causing problems.

---

Paying It Down

The 20% rule

Allocate 20% of each sprint to technical work. Not every sprint, every sprint. This prevents debt from accumulating faster than you pay it off.

If you have 50 points of capacity, 10 points go to tech debt. Every sprint. Non-negotiable.

Boy scout rule

"Leave the code better than you found it."

When you're in an area anyway, make small improvements. Rename a confusing variable. Extract a duplicated function. Add a missing test.

These tiny improvements compound over time.

Dedicated time

Some debt is too big for incremental improvement. Set aside focused time—a day, a week, whatever it needs.

The key: treat it like product work. Define scope, estimate effort, track progress.

---

Prevention

Easier to prevent debt than fix it.

Definition of done includes quality. A feature isn't done when it works—it's done when it works, has tests, and is documented.

Code review for maintainability. Reviewers should ask: "Will someone understand this in 6 months?"

Explicit shortcuts. When you take a shortcut to hit a deadline, log it. Create a ticket. Shortcuts are fine—invisible shortcuts become permanent.

Regular dependency updates. Falling behind on dependencies creates compounding debt. Update quarterly at minimum.

---

Talking to Business

The hardest part is often getting buy-in for technical work that doesn't ship features.

Translate to business impact:

Numbers help. "This refactor will take 2 weeks but will save 4 hours per developer per sprint" is more compelling than "we need to clean up the code."

---

Final thought

Some debt is strategic. Taking shortcuts to hit a critical deadline is fine—as long as you pay it back.

The problem is when shortcuts become permanent, accumulate interest, and eventually cripple your ability to ship.

Build the habits to prevent that. And when existing debt is slowing you down, address it systematically.