Measuring & Reducing Technical Debt

🔄 Quick Recall: In the previous lesson, you integrated AI review into your PR workflow. Now you’ll tackle technical debt — the accumulated cost of shortcuts, deferred quality, and evolving requirements that makes your codebase increasingly expensive to change.

Technical debt is like financial debt: manageable when tracked and controlled, catastrophic when invisible and growing. AI makes debt visible by scanning your entire codebase, quantifying the cleanup effort, and tracking whether the debt is growing or shrinking over time.

Debt Inventory

AI prompt for debt assessment:

Scan this codebase for technical debt. Files: [DESCRIBE CODEBASE OR PASTE KEY FILES]. Categorize debt by type: (1) Code smells — long functions, duplicate code, complex conditionals, God classes, (2) Missing tests — functions with business logic but no tests, especially error paths, (3) Outdated dependencies — packages with known vulnerabilities or major version updates available, (4) Inconsistent patterns — different parts of the codebase solving the same problem differently, (5) Dead code — unused functions, unreachable branches, commented-out code, (6) Documentation debt — undocumented public APIs, outdated README, misleading comments, (7) Security debt — hardcoded secrets, missing input validation, deprecated crypto. For each item: estimated hours to fix, severity (critical/high/medium/low), and which files are affected.

Debt categories and typical cost:

Prioritization Framework

AI prompt for debt prioritization:

Prioritize the technical debt items found in my codebase. Debt inventory: [LIST FROM PREVIOUS ANALYSIS]. Git history: [DESCRIBE WHICH AREAS ARE ACTIVELY DEVELOPED]. Create a priority matrix using two axes: (1) Risk — what’s the impact if this debt causes a problem (security breach, data loss, production outage, developer slowdown), (2) Change frequency — how often is this code modified (from git history: commits per month). Quadrants: High Risk + High Frequency = fix immediately, High Risk + Low Frequency = schedule soon, Low Risk + High Frequency = fix during next feature work, Low Risk + Low Frequency = monitor only. Generate a sprint-by-sprint plan for the top 20 items.

Boy Scout Rule Enforcement

AI prompt for incremental improvement:

Analyze this PR diff and suggest boy scout rule improvements — small changes that leave the code better than you found it without expanding the PR’s scope. Diff: [PASTE DIFF]. Suggestions should be: (1) In the files already being modified (don’t suggest changes to unrelated files), (2) Small enough to add to this PR without significant extra review time (under 10 lines), (3) Clearly beneficial (not subjective style preferences). Examples: rename an unclear variable you encountered, add a null check you noticed was missing, remove dead code you discovered, fix a typo in a comment you read. Each suggestion should take under 5 minutes to implement.

✅ Quick Check: A developer modifies a 200-line function to fix a bug on line 87. AI suggests extracting the 15-line block around the fix into its own function. Is this a good boy scout suggestion? (Answer: It depends. If the extraction is simple and makes the bug fix clearer, yes — it’s a small improvement in a file already being modified. If the extraction requires understanding the full 200-line function and adds risk, no — that’s a separate refactoring PR. Boy scout improvements should be low-risk additions to existing PRs, not scope expansions.)

Debt Tracking Dashboard

AI prompt for debt metrics:

Design a technical debt tracking dashboard. Metrics to track: (1) Total debt score — aggregate number representing overall codebase health (lower is better), (2) Debt by category — breakdown by type (security, testing, complexity, duplication), (3) Debt trend — is debt growing or shrinking over the last 30/60/90 days? (4) Debt per area — which parts of the codebase have the most debt? (5) Debt-to-change ratio — are we adding debt faster than we’re removing it? Define how each metric is calculated, what data sources are needed, and what constitutes a healthy vs. concerning trend.

Key Takeaways

• Quantified debt gets budgeted; vague debt gets ignored — AI scans the entire codebase and produces a debt inventory measured in developer-hours, giving management a concrete number to allocate resources against
• Debt prioritization should use risk × change frequency, not severity alone — a moderate issue in code that changes weekly costs more than a critical issue in code that hasn’t been modified in a year. AI cross-references static analysis with git history to produce this ranking
• The boy scout rule (leave code better than you found it) is more sustainable than dedicated cleanup sprints because it’s woven into daily work — AI enforces this by suggesting small, low-risk improvements in files already being modified
• A debt trend metric (growing vs. shrinking) is more important than the absolute debt number — a codebase with 100 hours of shrinking debt is healthier than one with 50 hours of growing debt
• Making debt visible (dashboard, PR reports, sprint review highlights) is what sustains the investment — when cleanup work is invisible, it always loses to feature pressure

Up Next

In the next lesson, you’ll build team code review practices — standards, feedback culture, and review efficiency that make the whole team better at writing and reviewing code.