Technical Debt

Technical debt is the implied future cost of choosing an expedient solution now instead of a better one. Ward Cunningham's metaphor compares it to a loan: the shortcut buys speed today, and you pay it back later with interest. The principal is the effort needed to fix the shortcut; the interest is the extra effort, defects and risk that every change in that area pays while the debt remains. It covers more than messy code: design, tests, dependencies, infrastructure and documentation can all carry it. Taken deliberately and repaid, debt is a legitimate tool; left unmanaged, it compounds until change becomes prohibitively expensive.

Principal is the one-off cost of removing the debt; interest is the recurring cost you pay for as long as it stays. At ShopNow, pricing logic duplicated across cart, checkout, order and invoice had a principal of about eight days, the effort to route everything through one PricingService. The interest was every promotion change touching four codebases, about half a day extra each time, plus two customer-visible price mismatches a quarter. The interest rate depends on how often the area changes multiplied by the pain per change. That is why the same ugly code can be expensive in a hotspot and almost free in a dormant module.

Martin Fowler's quadrant classifies debt on two axes: deliberate or inadvertent, and reckless or prudent. Deliberate and prudent debt is a conscious shortcut with a plan, such as hard-coding sale pricing for two weeks with an ADR and a repayment trigger; record it and repay it. Deliberate and reckless debt means knowingly cutting corners without a plan, which should be challenged in design review. Inadvertent and prudent debt is normal learning: you discover a better design afterwards and refactor as understanding improves. Inadvertent and reckless debt comes from gaps in skill and needs training, reviews and templates. Each quadrant needs a different response.

No. Deliberate, prudent debt can be a good business decision when speed matters more than perfection, for example meeting a Diwali sale deadline or validating a product before investing in its design. The conditions are that it is decided explicitly, recorded in an ADR and the debt register, contained behind a flag or interface, and given a repayment trigger such as the sprint after the sale. Debt in code that rarely changes also costs almost nothing and can be left alone. What is bad is invisible, unowned debt, and reckless debt labelled as an MVP with no plan to repay it, because its interest compounds silently.

Follow the interest, using evidence rather than code aesthetics. Run a hotspot analysis: code that is both complex and frequently changed, measured by Git churn multiplied by complexity, is where debt charges the most interest. Add change-coupling analysis to find files that always change together, which reveals scattered design debt. Combine this with defect density per module from the issue tracker, lead time per module from pull-request data, incident post-mortems, and developer pain from retros and on-call notes. At ShopNow, OrderService had 142 commits in six months and high complexity, so it ranked first, while a very complex but dormant report module did not rank at all.

Each entry needs enough information to support a funding decision. Include an id and title, the kind of debt, such as design, test, dependency or infrastructure, and an owning team. Record interest with evidence, such as change frequency, defects and extra effort per change, and the principal, the estimated effort to fix it. Add a repayment trigger, for example before the next promotions feature, and a status. Link the ADR if the debt was deliberate, and any incidents it caused. ShopNow keeps the register as YAML files in each repository, so entries are reviewed with code, referenced from pull requests and reported to leadership every quarter.

Speak in delivery and risk, not code quality. Product managers will not fund a refactoring sprint, but they will fund a faster roadmap. Show that promotion features take twice as long because of duplicated pricing, that repaying it first delivers the next three features in 23 days instead of 27, or that untested refunds risk a Sev-1 incident costing a stated sum. Back this with lead-time, defect and incident data. Then use three mechanisms: a standing share of capacity, around 20%, for continuous repayment; repayment bundled into the features that touch the debt; and dedicated projects for large hotspots, approved like any other investment.

Automate it and track it as a platform KPI. Use OpenRewrite recipes to perform most of a framework or JDK upgrade automatically, for example Spring Boot and Java 25 migrations, and Renovate or Dependabot for routine version bumps. Centralise versions with a shared BOM or Gradle platform so services move together. Report the percentage of services on supported versions to engineering leadership, and schedule the remaining manual work by service criticality. When 34 ShopNow services sat on end-of-life Spring Boot 2.7, recipes did about 80% of the work. Good tests and canary deploys make frequent upgrades safe, so dependency debt never accumulates into a big-bang migration.

Usually not. Debt only charges interest when code changes, so a legacy module that changes twice in two years costs almost nothing however ugly it is, and refactoring it carries risk for little return. ShopNow left such a report module alone, fenced it with characterisation tests and spent the effort on hotspots instead. The exceptions matter: if the code is about to become active because of a planned feature, if it carries security or compliance risk such as unsupported crypto libraries, or if it blocks a platform migration, repay it or replace it with a strangler. The decision follows interest and risk, not appearance.

Architecture decides how far debt spreads and how expensive it becomes. Good boundaries, with modules or services behind clear interfaces, contain debt, so a messy implementation inside one module does not leak into every change elsewhere and can later be replaced with a strangler. Poor boundaries turn local shortcuts into structural debt that touches many teams, visible as change coupling between components. Architects also prevent new debt with fitness functions: ArchUnit rules, dependency checks and module boundaries enforced in the build. Finally, architectural debt, such as a wrong service decomposition, is the most expensive kind, so it is tracked and prioritised explicitly.