Dev diary - 19. November 2026

Managing technical debt in legacy projects

header_image

Let's be honest: not every moment of a developer's career is fun, and some days the work is just hard. Dealing with technical debt is one of those challenges. Every profession has tasks that nobody enjoys, and ours is no different. These parts of the job deserve to be talked about too. Not every day is spent on work that fulfils us and takes our skills to the next level.

The situation

Our new team was asked to take over a project we knew very little about. We were replacing a team that had been building it for five years. The project was in bad shape in every respect. There was no documentation, and the project had accumulated significant technical debt: inconsistent formatting, questionable technical decisions, slow performance, and weak security.

Let's compare what the theory says you should do in this situation with what actually happened.

What the theory says

1. Make it visible

  1. Log debt items in your issue tracker with a tech-debt label (what the issue is, its impact, and the effort required to fix it).
  2. Find hotspots with static analysis (e.g. SonarQube), churn × complexity analysis, dependency audits, and by looking at where bugs cluster.
  3. Ask the team where it hurts most.

2. Prioritize

  1. Fix these first: fragile code that changes often, security issues, and anything that blocks new features.
  2. Leave stable code that nobody touches alone.
  3. Explain items in business terms: "This will speed up feature X."

3. Add a safety net

  1. Write tests around legacy code before you change it.
  2. Run CI on every pull request, and set up monitoring and error tracking.

4. Pay it down steadily

  1. Spend 15–20% of every sprint on debt.
  2. Follow the Boy Scout Rule: leave the code a little cleaner than you found it.
  3. Make small refactors instead of big rewrites. Use the Strangler Fig pattern to replace old code piece by piece.
  4. Upgrade dependencies regularly.
Legacy system and New services, technical debt

5. Stop new debt

  1. Have a Definition of Done (tests, review, no new warnings).
  2. Add CI quality gates (linting, coverage, security scans).
  3. Create a ticket right away for every deliberate shortcut.

6. Measure and communicate

  1. Track build time, lead time, bug count, and change failure rate.
  2. Show stakeholders the improvements.
  3. Review the debt register once a quarter.

What reality looked like

There was an endless stream of feature requests and very little time for refactoring.

Make it visible: the most important step

If I had to pick one point, it would be the first one: make it visible. When dealing with technical debt, the most important thing you can do is point out the problems and the risks.

Security matters most. We were almost certain the application had vulnerabilities. Once we raised the issue, the team responsible for security turned its attention to our application. They wrote penetration tests and ran them against our app. For every issue they found, they also gave us expert recommendations and step-by-step guidance on how best to mitigate the threat.

The second thing worth flagging is that new features take longer to deliver. Code like this takes much more time to read, build features on, refactor, and test. Saying so openly takes pressure off developers. It also makes delivery more transparent and improves collaboration overall.

Resist the big refactor

The second key to continuing to deliver new features is to avoid big refactors, even when you feel the urge to clean up one more line or one more method. Just don't do it.

Almost every time we refactored beyond the feature we were working on, we paid for it. It cost us a lot of time and set off a chain of further refactors. Once we started refactoring something during the development of a new feature or a bug fix, we often couldn't stop. The refactor grew into a huge pull request that caused many new problems, and in the end, we had to throw it away anyway.

What worked for us was making the smallest possible improvements, as often as possible. Sometimes that meant adapting to a bad solution. But in the end, it didn't cost much time, and the pull requests were easier to read and caused fewer bugs and problems.

Step by step, an unstable project slowly turns into a better and better product. A team rarely gets a dedicated block of time for refactoring. That's why it's essential to agree on a plan for managing technical debt and keeping the code maintainable.

Final thoughts

For me, the biggest challenge in implementing any requirement is writing scalable, readable, and efficient source code. Sometimes I delete my third solution and go back to the first one, and the delivery date slips by more than I planned. From experience, though, time invested this way can pay you back many times over.

This work is invisible, and at first glance, it doesn't seem to add much value. But well-written source code is what sets a product apart from the rest. Even when something is supposed to be a quick throwaway, you never know if your proof of concept will become a product that more than ten developers work on for over five years. That's exactly what happened to us.

Read more

Contact us

Let's talk