Technical debt often becomes a label for everything developers would prefer to change. Missing tests, difficult code, ageing dependencies and unclear accounts then land on one list. These topics require different decisions. A useful priority begins with an explainable operational cost or risk rather than the size of somebody’s irritation.
This guide treats technical debt as a practical improvement agenda. Examples and numbers are fictional. They illustrate how a team can choose between continuing, targeted remediation and investigation without immediately treating a complicated codebase as worthless.
Translate a technical label into a concrete consequence
Poor architecture is not a sufficiently bounded finding. Explain which change becomes difficult, which failure is hard to trace or which operational task depends on one person. A large module may remain stable for years while a small script needs manual repair every month. Code size alone does not identify the improvement with the greatest practical value.
Ask for one recent example. What work was required, where did uncertainty arise and what evidence remains? Record when the problem does not occur too. This keeps the description testable. A discussion about personal coding preferences can then become a discussion about change effort, error exposure or recoverability.
Distinguish different kinds of debt
A supported but confusing module may need explanation and targeted tests. A dependency without a workable maintenance path may need investigation of replacement or isolation. An unknown backup condition first calls for a recovery exercise. Calling all three technical debt hides the fact that each needs a different first action.
Classify work by the decision required: demonstrate behaviour, establish ownership, correct a defect or make future change easier. Use this alongside the technical category. It helps a business owner understand why transferring an account may precede a visible product improvement. The question is which dependency currently constrains the organisation, not which activity sounds most attractive.
Create a small evidence-based debt register
A useful register includes the topic, affected business journey, observation, possible consequence and uncertainty. Add a proposed first step. Complete replacement is usually too large as the first line of such a register. Investigating one integration or adding a test around an error-prone calculation is more concrete and easier to assess.
Keep the initial inventory manageable. Dozens of unordered comments create a misleading sense of completeness. Show which issues are related and where one intervention might reduce several symptoms. Also state what information is missing. An unknown consequence may justify investigation, but it should not be added to the total as demonstrated damage.
| Observation | Business question | Initial action | Possible evidence |
|---|---|---|---|
| An import failure cannot be traced to one enquiry. | Which outstanding enquiries could therefore remain unfinished? | Establish a reference and diagnosis path for one flow. | A second operator explains the same rejected example. |
| Changes repeatedly require the same manual follow-up check. | Which outcomes must remain consistent for every release? | Create a small set of recognisable reference examples. | The same examples are assessed before and after change. |
| An account has only one known administrator. | Which operations stop when that individual is unavailable? | Investigate ownership, cover and the allowed recovery path. | An authorised replacement reaches the required operating function. |
Compare targeted improvements with phased replacement before choosing a complete rebuild: Modernise or rebuild existing software: compare the whole transition.
Assess consequence and timing separately
An issue may be severe yet affect a function being retired. A less visible dependency may block every planned change. Discuss both the possible consequence and when action is needed. Involve the people responsible for the business process and technical implementation.
A simple order might be to make the situation manageable, introduce a targeted change and reassess. This is not a universal scoring formula. An absent recovery path might first need a temporary fallback and an exercise. Once the missing elements are understood, the team can choose an appropriate technical response. Avoid false precision by assigning neat probability and impact numbers without evidence.
Compare improvements using consistent assumptions
Illustrative example: a team manually checks order totals during every release. It also wants to rebuild the entire interface. One improvement could establish a fixed set of reference orders and a repeatable comparison. The team can assess reduced manual checking and more explainable failures rather than merely a different technical appearance.
Suppose planning examines six comparable releases. Record the team’s measured checking time and the effort required to maintain the new checks. Multiply comparable activities only. Released capacity does not automatically reduce the payroll bill. A larger interface change may be worthwhile, but it needs its own user and maintenance objectives rather than claiming the same saving.
Protect existing behaviour before restructuring
An internal code improvement should preserve the relevant business rules. Establish examples of intended behaviour first, including exceptions. Existing behaviour is not automatically desired behaviour: ask the process owner which deviations are defects and which reflect necessary historical agreements.
Choose checks that reveal whether the change preserves the intended outcome. This might involve a calculation, export or complete user journey. Tests have boundaries; a passing set does not cover every imaginable situation. Record which checks remain manual. That is more useful than a general promise that restructuring cannot introduce risk.
Reduce coupling where it serves a purpose
If one component is repeatedly reshaped around an external system’s meaning, an explicit translation boundary may help. Define incoming information, valid internal states and returned exceptions. An extra layer is useful only when responsibility becomes clearer rather than simply moving maintenance effort elsewhere.
Microsoft describes an anti-corruption layer as a pattern for separating different models. This does not mean every integration needs one. First investigate which change should become easier. Request a small before-and-after example including failure handling. That lets the organisation assess the benefit without relying solely on an architecture diagram.
Plan improvement work with an observable endpoint
Connect an improvement assignment to an assessable result: a second developer can start the test environment, a failure can be located through a reference, or a change no longer requires editing three other modules. Specify the comparison that makes sense. Not every improvement immediately produces a faster screen.
Agree what the assignment excludes too. A focused configuration-management improvement need not replace the entire infrastructure. Allow for discovered dependencies and identify a decision point if they alter scope. This lets the team make valuable small changes without treating technical debt as an unlimited maintenance bill.
Revisit the agenda when the product changes
A debt register should change. Retiring a feature may remove its improvement item. A new customer group using the application differently may make an earlier limited concern more important. Reassess around meaningful product changes and actual incidents instead of automatically implementing every old note.
Preserve the reason an item was deferred or closed. A future developer should not need to reconstruct the same discussion. Also ask whether the original problem has become less frequent or less consequential. Completing a technical task is not proof of business improvement. Connecting those outcomes remains a shared responsibility between the developer and process owner.
Turn the explanation into a project decision
Record your assumptions, unknowns and acceptance checks in the matching tool. Use the service guides to discuss delivery and scope.
Open the preparation tool ↗Questions about this topic
Is technical debt always bad?
No. A temporary decision can be deliberate and appropriate. Problems arise when consequences, ownership or follow-up remain unclear. Assess the decision in today’s business context.
How much budget should go to technical debt?
There is no suitable fixed percentage for every team. Connect effort to demonstrated friction, upcoming changes and continuity concerns. Agree concrete endpoints rather than allocating time alone.
When does a complete rewrite help?
That needs a separate comparison with retention, targeted improvement and gradual replacement. Include data, user journeys, temporary dual operation and maintenance. A list of technical irritations is insufficient justification.
Continue with a related question
From audit finding to improvement: evidence, priority and retesting
Assess technical findings through evidence, business impact, uncertainty, dependencies and a verifiable follow-up assignment.
Existing software & auditsModernise or rebuild existing software: compare the whole transition
Compare retention, targeted improvement, gradual replacement and rebuilding through user value, data, temporary complexity and operability.
Existing software & auditsScoping a software audit: which decision should the evidence support?
Define a useful software audit through investigation questions, system boundaries, samples, access, evidence levels and practical follow-up.
Custom software & portalsWhat does custom software cost? Compare scope, uncertainty and operation
Examine software costs through concrete workflows, dependencies, implementation, usage and maintenance rather than an isolated starting price.
Sources and technical background
- Google SRE: Testing for Reliability ↗
Background on targeted reliability testing; the exercises and acceptance agreements are original examples.
- Microsoft Azure Architecture: Anti-Corruption Layer ↗
A translation boundary can separate different system models; the example here is original project guidance.