Managing Technical Debt: When to Pay It Down vs Ship Features

Technical debt isn't inherently bad. Deliberate shortcuts that let you ship faster are valid trade-offs. Unmanaged debt that slows every future feature is the problem.

The Two Types of Debt

Deliberate debt: 'We know this is messy, we'll fix it later.' You made an explicit trade-off to ship faster.

Inadvertent debt: you didn't know better at the time. You learned, and now the code is a liability.

Both are normal. Only inadvertent debt is actually a problem — and only when it's unaddressed.

When to Ship Features Anyway

Prioritize features when:

• The debt doesn't slow down the feature you're building
• You're pre-product-market fit (validate first, optimize later)
• The debt is isolated to areas unlikely to change
• Revenue depends on shipping this

When to Pay Down Debt First

Pay down debt when:

• Every new feature requires touching the messy code
• Bug rate is increasing in the affected area
• New engineers can't onboard without a guided tour
• You've been 'shipping around' the problem for 3+ months

The 20% Rule

A practical allocation:

80% feature work
20% technical debt / refactoring

This isn't a hard rule — adjust based on your stage. Pre-PMF: 90/10. Post-PMF scaling: 70/30.

Making Debt Visible

// Use TODO comments with context
// TODO(tech-debt): This runs O(n²) — refactor to use a Map when traffic > 1k/day
// See: https://linear.app/your-team/issue/ENG-234
function findDuplicates(items: Item[]) {
  return items.filter((item, i) =>
    items.findIndex(x => x.id === item.id) !== i
  );
}

Track debt in your issue tracker with a tech-debt label. Review it quarterly. Delete tickets for debt in areas you'll never touch again.

The Strangler Fig Pattern

Don't rewrite — incrementally replace:

1. New code goes in the new system
2. Old code stays until you migrate its callers
3. Delete old code when nothing points to it

This works because you never have two half-finished systems — you always have one working system and one in progress.

Ship Fast Without Creating Debt

The best way to manage debt: create less of it. The Ship Fast Skill Pack includes Claude Code workflows for generating tests, PR review, and architecture analysis — so you ship fast AND stay clean.