Technical debt
How to prioritize technical debt
Every codebase carries debt. The engineering lead's job is not to eliminate it but to decide which debt is worth paying down, when, and how to explain that choice to people who do not read code. This guide gives you a way to classify, score and schedule it.
What counts as technical debt
Ward Cunningham introduced the debt metaphor to describe how shipping code with an incomplete understanding creates future cost, like interest on a loan. In practice teams use the term for anything in the system that makes future change slower or riskier than it needs to be:
- code that is hard to understand or change;
- missing or unreliable tests;
- outdated dependencies, frameworks or runtimes;
- architecture that no longer fits the product;
- manual steps in build, release or operations;
- missing documentation for decisions and systems.
Not every imperfection is debt. Code that is ugly but rarely touched and working fine may cost almost nothing to leave alone.
Classify it first: the debt quadrant
Martin Fowler's technical debt quadrant sorts debt on two axes: whether it was taken on deliberately or inadvertently, and whether the decision was prudent or reckless.
| Reckless | Prudent | |
|---|---|---|
| Deliberate | "We don't have time for design." | "We must ship now and will deal with the consequences." |
| Inadvertent | "What's layering?" | "Now we know how we should have done it." |
The quadrant helps a lead respond to causes, not just symptoms. Prudent deliberate debt needs a repayment plan. Reckless debt points to a skills or process problem that will keep creating more.
AI tools and new kinds of debt
AI assistants can reduce debt, for example by speeding up migrations and test writing. They can also add it faster than before:
- Duplicated logic: a tool writes a new helper rather than finding the existing one.
- Inconsistent patterns: several ways of doing the same thing, each plausible.
- Unowned code: changes merged that nobody on the team fully understands.
- Test debt: generated tests that pass but do not prove the right behavior.
Review standards are the first defense; see reviewing AI-generated code. A consistent codebase also helps the tools, because they tend to follow the patterns they see.
Score what you find
Keep a debt register: one entry per item, in the same tracker as other work. Score each item on a few factors, using a simple 1–3 scale:
| Factor | Question |
|---|---|
| Impact | How much does this slow down or endanger work today? |
| Frequency | How often does the team touch this area? |
| Risk | Could it cause an incident, a security problem or data loss? |
| Trend | Is it getting worse as more code builds on it? |
| Cost to fix | How much effort, and can it be done in increments? |
| Deadline | Is there a date after which it becomes urgent, such as end of support for a dependency? |
A simple priority: items with high impact, high frequency and high risk that can be fixed in increments come first. Items in rarely touched code with low risk can wait, however unpleasant they look.
Frequency deserves special weight. Debt concentrated in the files the team changes most often costs something every week. Version control history can show which files change most, and incident reports can show which areas fail most.
Schedule it
| Approach | How it works | Works well when |
|---|---|---|
| Reserved capacity | A fixed share of each cycle goes to debt, agreed with product | Debt is steady and spread out |
| Fix as you go | Improve code you are already changing for a feature | Debt sits in areas under active development |
| Dedicated project | A planned, scoped piece of work with its own goal | Debt is large and structural, such as a migration |
| Stop-the-line | Pause feature work to fix a risk | Security exposure or repeated incidents |
Whichever approach you use, agree the share of capacity with your product partner in advance, and write it down. Renegotiating each sprint wastes time and usually loses.
Explaining debt to non-engineers
Stakeholders care about outcomes. Translate each important debt item into one of these:
- Speed: "Changes in billing take about twice as long as elsewhere because of this."
- Risk: "This library stops receiving security fixes at the end of the year."
- Reliability: "Three of the last five incidents started in this component."
- Hiring and onboarding: "New engineers take longest to become productive here."
Use your own numbers from your tracker and incident reports. Estimates you cannot back up weaken the case. Tie the plan to delivery measures; see measuring engineering work.
Record decisions so debt is visible
Architecture decision records, a format popularized by Michael Nygard, capture a decision's context, the decision itself, and its consequences. When a team deliberately takes on debt, an ADR records why and what would trigger repayment. Future engineers, and future AI tools reading the repository, then have the context.
Preventing new debt
- Agree on a definition of done that includes tests, documentation and operational readiness.
- Keep changes small and reviewable, especially AI-assisted ones.
- When the team takes a shortcut on purpose, log it in the register the same day.
- Upgrade dependencies regularly in small steps rather than in rare, large jumps.
- Review debt trends in retrospectives, not only when something breaks.
Common questions
How much time should a team spend on technical debt?
There is no universal share. It depends on the age of the system, the rate of change and the risk. Pick a starting share with your product partner, review it each quarter, and adjust based on whether delivery and incident trends improve.
Should we have a "debt sprint"?
It can clear a backlog, but debt returns if normal work keeps creating it. Most teams need a steady allowance as well.
Who decides what debt to fix?
The team identifies and scores it; the lead proposes priorities; the lead and product partner agree on capacity. Engineers closest to the code usually know where it hurts most.
Is a rewrite ever the answer?
Sometimes, but incremental replacement is usually lower risk because it keeps delivering value and can be stopped. Treat a rewrite as a project with its own goals and checkpoints. New leads can find more on setting direction in the first 90 days.
Last reviewed 2026-09-17