Technical debt

📘What it really is

• Technical debt is the future cost of shortcuts and of code that no longer fits: every change in that area takes longer and risks more bugs. The "interest" is the extra time and risk on every future change.

• Kinds:

• deliberate and prudent: "we'll launch with manual tutor onboarding and automate it next quarter" (a sensible choice, written down);
• accidental: design that made sense once but doesn't fit the business any more; things nobody understood at the time;
• reckless: skipping tests, copy-pasting, ignoring errors to hit a date;
• outdated dependencies and platforms (Module 78): old framework versions, unsupported runtimes;

• missing tests, documentation and monitoring.

• Signs: simple changes take days; the same bugs return; people avoid certain files; onboarding is slow; deploys are scary.

• Managing it:
• make it visible: a debt register (or labelled backlog items) with the area, the problem, the "interest" (how it slows or risks work) and the fix effort;
• prioritise by interest: fix debt in areas you change often; debt in code nobody touches can wait;
• budget for it: a steady share of each sprint (often 10 to 20%) for debt and upkeep, plus larger planned pieces on the roadmap (Module 97);
• the Boy Scout rule: leave code a little better than you found it, as part of normal work;
• refactor safely: tests first, small steps, CI (Modules 29 and 71);
• prevent new debt: code review, Definition of Done (Module 98), ADRs that record deliberate shortcuts and when to repay them.
• AI-generated code can add debt fast if it isn't understood and reviewed (Builder Path Lesson 5): volume isn't quality.