Technical Debt: Examples and How to Explain It

1. What is technical debt?

Technical debt is the gap between how your code or infrastructure looks and how it should look. Ward Cunningham coined the term in 1992 while explaining to managers at a finance company why the team had to go back to code that already worked. Martin Fowler covers the metaphor in more detail.

But not every flaw is debt. A bug is a place where the app doesn't do what it should. With debt, the app works, but every further change costs more time and carries more risk. That extra time is the interest; refactoring, an upgrade or a rewrite is the repayment.

Not all debt is taken on deliberately. It can come from a lack of knowledge or from changes in requirements, technology or the environment.

2. Types of technical debt with examples

Technical debt isn't only in the code. Grouping it by where it lives helps with planning, because each type gets paid off differently.

3. Signs technical debt is slowing you down

Technical debt shows up in numbers the team often already tracks. Changes to one module keep taking longer than estimated, bugs keep coming back to the same part of the code and nobody wants to take on an upgrade because that part is inconsistent with the rest of the app.

Knowledge that only lives in someone's head is another sign. When only the author knows about a workaround or it's written in a `TODO` comment in the code, support can't tell whether a reported bug is a known issue. A new developer then runs into it on their own.

4. Documenting technical debt: what to record for each item

Technical debt documentation, or a technical debt register, is a list of problems with an estimate of their complexity, cost or time. It works best as a `tech-debt` label in your issue tracker (GitHub Issues, GitLab, Jira), where the team sees it next to regular work. A separate document outside the backlog usually stops getting updated.

Title: Payment module uses an old version of the payment gateway SDK
Labels: tech-debt, payments
Interest: a new payment method takes 4 days instead of 1; the SDK gets no security fixes
Risk: the gateway drops support for the old API version on 2027-06-30
Estimate: 3 days (SDK swap and payment tests)
When: before adding Apple Pay, planned for Q1
Recorded by: backend developer, reviewed 2026-10-28

5. How to pay off and reduce technical debt

You remove technical debt by bringing the affected part of the app back to a state where the team can change it quickly and safely. The main tool is refactoring: changing the internal structure of code without changing what it does. Depending on the type of debt, it also takes dependency updates, modernizing the architecture or adding tests.

Before you refactor, add tests that pin down the current behavior, otherwise you won't know whether the change broke something. Pay off large debt in small steps you can deploy on their own. Rewriting a whole part is the last resort: it takes a long time and you maintain both the old and the new version in the meantime.

6. How to explain technical debt to your manager

Managers don't decide about code quality; they decide about time, cost and risk. So explain technical debt in those terms, with numbers from the register, not words like refactoring or coupling.

1. 1

   Start with the interest

   Say what the debt costs today: "Adding a payment method takes us 4 days instead of 1" or "The old library caused 2 incidents last quarter".

2. 2

   Name the risk and its date

   End of support for a framework or a payment gateway API version is a deadline a manager understands without a technical explanation.

3. 3

   Propose a small, specific repayment

   Instead of "we need a month for a rewrite", offer: "Before Apple Pay, we'll swap the SDK in 3 days and every method after that takes a day." A repayment tied to a planned feature is easier to approve.

4. 4

   Agree on regular capacity

   A fixed slice of every sprint or one day a month set aside for debt is more predictable than negotiating each item separately.

5. 5

   Show what the repayment brought

   After paying off an item, compare the time or incident count before and after. Next time you ask for capacity, you'll have numbers from your own project.

7. Managing technical debt in agile and Scrum

In Scrum and Kanban, technical debt belongs in the same backlog as features, otherwise it never gets picked up. The product owner then sees what a repayment costs and what it brings and can plan it into a sprint like any other work.

A Definition of Done that requires tests and updated documentation slows down new debt. Small debt can be paid off as you go: whoever changes a file for a feature also cleans up what's related to that feature.

8. Where the technical debt list lives after handover

Technical debt belongs in the project handover document and in the software maintenance plan. A list copied into the handover document goes stale with the first repayment or new item, though, so the document should link to the live register.

In AboutTheApp, you attach a link to the register to the app, for example a filter on the `tech-debt` label in GitHub Issues or Jira, under the Issue Tracking category. If the client shouldn't see it, mark the link as private: it only shows to signed-in team members or with an unlock code. AboutTheApp doesn't track the debt itself; it keeps the link to wherever the team does, next to the app's repository, environments and versions.

Frequently asked questions