Technical Debt
A way to describe design or implementation choices that provide near-term benefit while increasing the cost or risk of future software change.
Download Markdown (.md)Soroush’s Product Wiki · https://wiki.soroush.uk/topic/technical-debt/
01What it means
Technical debt is a metaphor for the future consequences of expedient or suboptimal technical choices. Like financial debt, a shortcut may be deliberate and useful when its immediate benefit exceeds its later cost; the continuing friction is the interest. Debt can also arise unintentionally through learning, changing requirements, aging dependencies, weak boundaries, or neglected maintenance. Not every imperfection is debt: the term is most useful when tied to a concrete impact on future work.[1][2]
Slower changes, incidents, support load, security exposure
Expedient design choiceDeliberate shortcut or local optimization
Changing contextRequirements, scale, architecture, dependencies
Neglected maintenanceAging tools, weak boundaries, missing automation
Compounding interestEvery future change pays coordination and risk cost
Not every imperfection is debt. The metaphor is useful when a concrete condition can be tied to future delay, risk, incidents, support burden, or reduced options.
02Why it matters
Unmanaged debt can slow delivery, increase defects, constrain product options, and make routine changes hazardous. Naming it helps teams discuss trade-offs between current value and future adaptability. A visible, evidence-based approach also prevents maintenance work from becoming an abstract request to make the code cleaner.
03When to use it
Use the concept when a technical condition imposes a recurring cost, blocks an important objective, or creates material operational risk. Record enough context to explain the affected capability, likely consequences, and repayment options. Address debt according to impact and timing rather than placing every concern in an undifferentiated backlog.
04How it works
- Describe the specific condition, why it exists, and the decisions or system boundaries involved.
- Connect it to observable effects such as delays, incidents, support burden, security exposure, or limited options.
- Estimate urgency, uncertainty, likely interest, and the cost of reducing or containing it.
- Choose deliberately among repayment, incremental refactoring, isolation, monitoring, acceptance, or retirement.
- Include reduction work in relevant feature or reliability plans instead of relying only on separate cleanup projects.
- Review the item as architecture, evidence, and business priorities change.
05A practical example
A retailer copied tax logic into six services to meet a deadline. Every regulatory change now requires coordinated edits and produces inconsistent rounding defects. The team measures incident and change effort, introduces one versioned calculation service, migrates consumers incrementally, and retires each duplicate rather than attempting a risky all-at-once rewrite.
06Where it breaks
The debt metaphor can oversimplify architecture and imply that every compromise must be repaid. Estimates of principal and interest are uncertain, and teams may label disliked code as debt without evidence. The term can also conceal chronic underinvestment or reckless decisions behind neutral language. Some systems will be retired before repayment becomes worthwhile.
Common mistakes
- Calling every defect, missing feature, or untidy file technical debt.
- Maintaining a large debt register without linking items to outcomes or decisions.
- Demanding complete repayment instead of reducing the highest-cost constraint incrementally.
- Using delivery pressure to justify shortcuts without recording ownership or review conditions.
07Sources
- A Field Study of Technical DebtCarnegie Mellon University Software Engineering Institute · Institutional research summaryA Field Study of Technical Debt
- Technical Debt QuadrantMartin Fowler · Professional technical articleTechnical Debt Quadrant