Technical Debt
Technical debt describes technical decisions or conditions that make future changes more difficult, risky, or expensive than they otherwise need to be.
It often results when a practical short-term decision creates longer-term maintenance work.
The Software Engineering Institute defines technical debt around design or implementation choices that are expedient in the short term but create a technical context in which future change becomes more costly or difficult. Carnegie Mellon SEI: Managing Technical Debt
What It Looks Like on a Website
Technical debt can include:
- Outdated dependencies
- Duplicate templates
- Hardcoded content
- Undocumented integrations
- Plugin Bloat
- Workarounds layered over older workarounds
- Old PHP or framework versions
- Inconsistent CSS
- Missing automated deployment
- Large amounts of custom code nobody understands
- Data structures built around an old design
- Broken development environments
Technical debt is not limited to messy code.
It can exist in architecture, infrastructure, deployment processes, tests, and documentation.
The Software Engineering Institute explicitly includes architecture, deployment infrastructure, documentation, and delayed technology updates within the broader technical-debt problem. Carnegie Mellon SEI: Recommendations for managing technical debt
Technical Debt Is Not Always a Mistake
A short-term compromise can be reasonable.
For example:
We need to launch this registration form before the event, so we'll use the existing system and replace it afterward.
The problem begins when:
Replace it afterward
never happens.
The temporary solution quietly becomes permanent infrastructure.
Why It Matters
Technical debt creates friction.
A change that should take an hour may take a day because:
- Several systems interact unexpectedly
- Nobody understands the original decision
- Updating one dependency breaks another
- Testing is difficult
- Production cannot be reproduced
- The safe path is unclear
The debt effectively charges interest through future maintenance effort.
Common Problems
Common problems include:
- Treating every imperfect solution as technical debt
- Never documenting intentional debt
- Continually postponing maintenance
- Complete rewrite proposed instead of targeted cleanup
- Technical debt described without explaining its consequence
- New features always prioritized over system health
How to Improve
Make meaningful technical debt visible.
Document:
- What the issue is
- Why it exists
- What problems it creates
- What would trigger fixing it
- Rough effort
- Risk of leaving it
Then address debt according to its actual cost and risk rather than pursuing technical perfection.