Technical debt slowing development: what to fix first

Technical debt slows development down once every new feature takes longer than the one before it. For the company, that means a roadmap that keeps slipping and developers who fight fires instead of building.

You can measure it without an expensive tool, from git history and bugs. Fix the debt in the code that changes most often first, not the ugliest code.

AI writes all of our code today, and a senior is accountable for the result. Before this, Filip spent 7 years building one SaaS product. Debt in a product that lives for years is not solved in one sprint. You pay it down continuously.

How do you know technical debt is slowing you down?

Debt does not announce itself. It shows up as slowness everyone explains differently. A button that should take a day takes a week. Tick what is true for your team. Every unticked item is one debt signal.

How do you measure technical debt without an expensive tool?

You do not need a code analysis platform. You need an answer to one question: where do changes cost you the most?

The strongest signal is the first two rows combined. A file that changes often and also keeps producing bugs is debt with interest. One command gives you the list of the most changed files:

git log --since="6 months ago" --format= --name-only | sort | uniq -c | sort -rn | head -20

Next to each file in the output, note the bugs that touched it. The top few rows are your list.

What should you fix first?

Not what is ugliest. What costs you the most time right now. The order we use:

Aesthetics and moving to a newer framework "because it is newer" come last. Code nobody touches for months can stay ugly. It costs you nothing. If it is not used at all, we don't pay it down, we delete it. We do the same in our own repositories: unused code and tools nobody calls get removed.

If the debt in one part is so large that you are considering a rewrite, start the same way. Tests for the current behaviour first, the decision after. We cover tests and review that really stop a bad change in How to introduce AI into a development team.

How do you pay down debt without stopping the roadmap?

In the same flow as features. Not in a "refactoring sprint" that keeps getting pushed because an urgent feature came up.

• A fixed share of capacity. Agree on it with product up front and do not raid it at the first emergency.
• Pay down where you work. When you build a feature in an indebted module, clean it up in the same pull request.
• Test first, then change. A test for current behaviour catches what you would otherwise break.
• No new debt without a record. If you take a shortcut on purpose, log it as a task with the reason.

This is what it looks like on one roadmap feature:

AI changes the economics here. Tests for existing code, moves and renames used to be expensive, so they were put off. With AI they are cheap. Without rules and review, though, AI adds debt just as fast. We describe what we put in the repository for it in Rules for AI code in a team.

First steps for this month:

1. Pull the list of the most frequently changed files from git.
2. Next to each, note the bugs from recent months.
3. Pick three places that block the next roadmap feature.
4. Agree a fixed share of capacity for debt with product.
5. Check that CI can stop a bad merge.

When we don't recommend it

• The debt is not slowing you down, you just do not like it. If that code does not change, leave it. Put the capacity into the roadmap.
• The product is being shut down or replaced in a few months. Paying down debt in code that is ending does not pay off.

Want to pay down debt with someone who does this daily?

A senior plugs into your repository and pull requests from day one. They pay down the debt in the roadmap's way, alongside features, not instead of them. This is how we work as an external developer for product teams.

Tell us which part of the system slows you down most. We get back to you within two business days, and together we pick what to fix first.

If you'd rather talk first, book a 15-minute meeting with Filip.

Which file in your repository is the whole team afraid to open?

Frequently asked questions

How do you measure technical debt?

The simplest way is git history plus bugs. Files that change most often and also produce bugs are the debt that really costs you time. On top of that, watch how estimates grow for small changes.

What should you fix first?

Debt in the code you need for the next roadmap feature. Then frequently changed code with bugs. Leave code nobody touches alone, even if it is ugly.

How do you explain technical debt to management?

In time and risk, not code quality. Show how much longer changes take in a specific part and how many bugs come from it. Ideally on a roadmap feature management is waiting for.

Does AI increase technical debt?

Without rules and review, yes, because it writes fast and without context. With rules in the repository, tests and review by someone else, it helps pay debt down. Tests and moving code are cheap with AI.