How to Get Technical Debt in Web Projects Right
The accumulated cost of decisions that were reasonable at the time and have since made every change slower than it should be.
Marcus Adeyemi
Where most projects go wrong
The usual mistakes:
- A big-bang rewrite proposed as the only remedy
- Cleanup work with no stated outcome, which is the first thing cut
- Treating all debt as equal when most of it is in code nobody touches
- Letting dependency upgrades lapse until the jump is too large to make safely
What good looks like instead
- Write the debt down when you take it on, including what would repay it
- Repay debt in the areas you are actively changing rather than in a separate cleanup project
- Track the symptoms — lead time, defect rate — rather than arguing about the cause
- Keep dependencies current, because the cost of a delayed upgrade grows faster than the upgrade
Why it matters
Debt is not a moral failing, it is a financing decision — the problem is only that most teams take it on without recording it, so nobody can see what the interest is costing.
The specs that matter
| Measure | Figure |
|---|---|
| Two kinds | deliberate debt taken knowingly, and accidental debt discovered later |
| Where it shows up | lead time for changes, defect rate, onboarding time |
| The compounding cost | each shortcut makes the next change more expensive |
| Common carriers | unpatched dependencies, duplicated components, untested code paths |
Knowing when to hand it over
Tip: Bring in help when small changes routinely take weeks, when nobody on the team is willing to touch a particular area, or when a dependency has fallen far enough behind that upgrading is its own project.
Where this comes from
- Laravel Documentation — Upgrade guide
- OWASP — Vulnerable and outdated components
- GOV.UK Service Manual — Maintaining a service
The figures and practices above come from the sources listed.
Working on something like this?
We take on Web Design & Development work for teams who want it done once, properly. Tell us what you are building and we will tell you honestly whether we are the right studio for it. Start a project.
Where to go next
Spotted something wrong? Report an error on this page. We correct on the page and say what changed.
