Back to blog

Engineering

Technical Debt: When to Accept It and When to Pay It

8 min readEnviaIT Engineering

Every codebase has technical debt. Yours does, ours does, Google's does. The question is not whether you have it but whether you know where it is and have a plan for it. Most teams treat technical debt as something to feel guilty about — a pile of shortcuts that accumulates silently until the whole system grinds to a halt. That is the wrong framing.

At EnviaIT, we treat technical debt like financial debt: it is a tool. Used wisely, it lets you move faster when speed matters most. Mismanaged, it compounds until you are spending all your time on interest payments and none on building new value. This article shares the framework we use to classify, prioritize, and reduce technical debt across our projects.

What technical debt actually is (and is not)

The term "technical debt" was coined by Ward Cunningham in 1992, and it has been misused ever since. Technical debt is not the same as bad code. Here is the distinction:

  • Technical debt: A deliberate or incidental trade-off where you accept a suboptimal implementation now, knowing it will cost more to change later.
  • Bad code: Code that is poorly written due to lack of skill, care, or understanding. This is not debt — it is damage.

The difference matters because debt implies a conscious decision with a known cost, while bad code implies a problem that needs fixing regardless of business context.

The quadrant: four types of technical debt

Martin Fowler's technical debt quadrant is the most useful classification we have found. It maps debt along two axes: deliberate vs. inadvertent and reckless vs. prudent.

| | Reckless | Prudent | |---|---|---| | Deliberate | "We don't have time for design" | "We must ship now and will deal with the consequences" | | Inadvertent | "What is a design pattern?" | "Now we know how we should have built it" |

Each quadrant calls for a different response:

Deliberate + Prudent (strategic debt)

This is the "good" debt. You know the trade-off, you document it, and you have a plan to pay it back. Example: using a simpler authentication system for an MVP launch, with a ticket already created to implement proper RBAC in the next sprint.

Our approach: Accept it freely, but always create a tracking ticket with context on why the shortcut was taken and what the proper solution looks like.

Deliberate + Reckless (dangerous debt)

This is cutting corners without caring about consequences. "We'll just hardcode these values." "Skip the tests, we'll add them later" (you will not). This type of debt compounds fastest because nobody documents it and nobody plans to fix it.

Our approach: Block it in code review. This is the one type of debt we actively refuse to accept.

Inadvertent + Prudent (natural debt)

This is the debt you discover after the fact. You built the system correctly given what you knew, but now you understand the domain better and see a superior approach. This is the most common type of debt in growing products.

Our approach: Track it, but do not rush to fix it. It only becomes urgent when it starts impeding new feature development.

Inadvertent + Reckless (incompetence debt)

This comes from lack of knowledge or experience. A junior developer who does not know about SQL injection creates a security vulnerability, not a debt decision. The fix is education and better review processes, not a debt management framework.

Our approach: Address through mentorship, pair programming, and thorough code review.

How to measure technical debt

You cannot manage what you cannot see. Here are the signals we use to identify and quantify technical debt across our projects:

Lead indicators (debt is growing)

  • Increasing PR cycle time: If pull requests that used to take 1 day to merge now take 3, the codebase is becoming harder to work with.
  • Rising bug escape rate: More bugs reaching production suggests the system is becoming fragile.
  • Developer complaints: This sounds soft, but if multiple engineers independently say "this module is a nightmare to work in," that is data.
  • Expanding "blast radius" of changes: When a small feature change requires touching 15 files across 6 modules, coupling is too high.

Lag indicators (debt is costing you)

  • Velocity decline: The team is shipping fewer story points per sprint with the same headcount.
  • Onboarding time: New developers take longer to become productive.
  • Incident frequency: Production issues are becoming more common, especially in areas that haven't been deliberately changed.

Quantitative tools

We use a combination of automated tools to surface debt:

# Static analysis for code quality trends
npx eslint --format json . | jq '.[] | .errorCount' | paste -sd+ | bc

# Complexity metrics (cyclomatic complexity)
npx ts-complexity-report --threshold 15 src/

# Dependency freshness
npx npm-check-updates --format json

# Test coverage trends (not a direct debt measure,
# but low coverage correlates with high change risk)
npx jest --coverage --coverageReporters=json-summary

None of these tools alone tells you "you have X dollars of technical debt." But tracked over time as trends, they give you a reliable picture of whether debt is growing or shrinking.

Our prioritization framework

Not all debt is worth paying right now. Some debt is cheap to carry and expensive to fix. Other debt is expensive to carry and cheap to fix. The trick is telling them apart.

We use a simple 2x2 matrix based on impact (how much this debt slows us down) and effort (how hard it is to fix):

| | Low Effort | High Effort | |---|---|---| | High Impact | Fix immediately (quick wins) | Plan for next quarter | | Low Impact | Fix opportunistically | Probably never fix |

Scoring criteria

Impact score (1-5):

  1. Rarely encountered, affects no one
  2. Occasionally annoying, easy to work around
  3. Regularly slows down development in one area
  4. Blocks or significantly slows multiple features
  5. Causes production incidents or blocks critical work

Effort score (1-5):

  1. Less than 1 day, single developer
  2. 1-3 days, single developer
  3. 1-2 weeks, may need coordination
  4. Multiple weeks, affects several modules
  5. Major rewrite, cross-team effort

We track these scores in a simple spreadsheet that gets reviewed monthly. Items scoring high impact / low effort get added to the next sprint. High impact / high effort items get scheduled as dedicated "health sprints" once per quarter.

Refactoring strategies that work

Once you have identified the debt worth paying, the question becomes how. Large-scale refactoring is where most teams fail — not because the technical work is impossible, but because they try to do it all at once.

The strangler fig pattern

Named after the tropical fig that gradually envelops and replaces its host tree, this pattern works beautifully for replacing legacy modules:

  1. Build the new implementation alongside the old one
  2. Route new traffic/features to the new implementation
  3. Gradually migrate existing functionality
  4. Remove the old code when nothing depends on it
// Phase 1: New service alongside old one
class NotificationService {
  async send(notification: Notification) {
    if (featureFlag("use-new-notification-pipeline")) {
      return this.newPipeline.send(notification);
    }
    return this.legacyPipeline.send(notification);
  }
}

// Phase 2: Migrate by notification type
// Phase 3: Remove legacy pipeline entirely

We used this exact approach when migrating Nudato's notification system from a polling-based architecture to an event-driven one. The migration took 6 weeks, and the platform had zero downtime during the transition.

The boy scout rule

"Leave the campground cleaner than you found it." Every time a developer touches a file, they improve one small thing: rename a confusing variable, extract a method, add a missing type annotation. Over weeks and months, this adds up significantly.

We enforce this through a simple code review checklist item: "Did you leave this file better than you found it?" It is not mandatory to refactor the whole module, but improving naming, removing dead code, or adding a comment costs minutes and pays dividends.

Dedicated health sprints

Once per quarter, we dedicate a full sprint to technical health. No new features, no stakeholder demos — just paying down debt. This sprint is sacred. We protect it from scope creep the same way we protect feature sprints.

A typical health sprint includes:

  • Dependency updates (especially security patches)
  • Addressing the top 3-5 items from our debt backlog
  • Improving test coverage in the highest-risk modules
  • Updating documentation that has drifted from reality

When to rewrite vs. when to refactor

The "big rewrite" is one of the most dangerous decisions in software engineering. Joel Spolsky called it "the single worst strategic mistake that any software company can make." We mostly agree, but not always.

Refactor when:

  • The core architecture is sound but the implementation is messy
  • The domain model is correct but the code has accumulated cruft
  • You can make incremental improvements without breaking the system
  • The team understands the current system well enough to evolve it

Rewrite when:

  • The technology is genuinely end-of-life (no security updates, no community)
  • The architecture fundamentally cannot support the next phase of the product
  • The cost of ongoing maintenance exceeds the cost of rebuilding
  • You have a clear, validated specification for what the new system needs to do

If you decide to rewrite, do it incrementally. A "big bang" rewrite that tries to replace everything at once has a failure rate north of 70%. Use the strangler fig pattern instead.

A real example

One of our clients came to us with a PHP 5.6 monolith that powered their B2B marketplace. The framework was no longer receiving security patches, the codebase had no tests, and adding a single feature took 3-4 weeks. We evaluated two options:

  • Refactor: Upgrade PHP, add tests, modernize gradually. Estimated 6 months of part-time work.
  • Incremental rewrite: Build new features in a Next.js application, proxy legacy routes to the old system, migrate module by module. Estimated 9 months total, but new features could ship in the new stack from month 2.

We chose the incremental rewrite. By month 3, the client was shipping new features at 3x the previous velocity in the new stack while the legacy system was slowly being retired. By month 8, the legacy system handled only payment processing (the last module to migrate), and by month 10, it was fully decommissioned.

The business case for paying debt

The hardest part of managing technical debt is often not the technical work but convincing stakeholders that it matters. Product managers and executives care about features, revenue, and deadlines — not code quality abstractions.

Here is how we frame the conversation:

  1. Translate to business metrics. "Our deployment frequency has dropped from 3 per week to 1 per week. That means features reach customers 3x slower."

  2. Quantify the cost of inaction. "Every new feature in the billing module takes 40% longer because of the current state of the code. Over the next quarter, that is approximately 3 weeks of lost development time."

  3. Propose a trade-off, not a blank check. "If we spend 2 weeks on the billing module refactor, we estimate the next 4 billing features will each take 30% less time. Net positive within 2 months."

  4. Show, do not tell. Track velocity before and after a health sprint. The numbers speak for themselves.

How we track debt at EnviaIT

Our process is deliberately simple:

  1. Tag it when you see it. Developers add a // TECH-DEBT: comment in the code with a one-line description. Our linter extracts these into a report.

  2. Log it in the backlog. Every TECH-DEBT comment gets a corresponding ticket with impact/effort scores.

  3. Review monthly. The tech lead reviews the debt backlog, re-scores items based on current priorities, and proposes items for the next sprint.

  4. Dedicate quarterly. One sprint per quarter is fully dedicated to debt reduction.

  5. Measure trends. We track total debt items, average age of debt items, and the ratio of debt work to feature work. The target is keeping debt work at 15-20% of total engineering effort.

// TECH-DEBT: Replace manual date parsing with date-fns
// Impact: 3 (causes timezone bugs monthly)
// Effort: 1 (straightforward replacement)
// Ticket: ENG-1247
const parseDate = (str: string) => {
  const [day, month, year] = str.split("/");
  return new Date(+year, +month - 1, +day);
};

Conclusion

Technical debt is not a moral failing — it is an engineering reality. The teams that manage it well are not the ones that never accumulate it. They are the ones that know what they owe, why they owe it, and when they plan to pay it back.

The framework is straightforward: classify your debt, measure its impact, prioritize ruthlessly, refactor incrementally, and make the business case with data. Do this consistently, and your codebase stays healthy enough to support whatever the business needs next.

Struggling with technical debt in your product? Let's talk about building a sustainable engineering roadmap.

Leer este artículo en Español →← All articles