Chapter 34: Key Takeaways

Managing Technical Debt

  1. AI-generated code creates technical debt differently than human-written code. The debt is often invisible because each AI-generated file looks clean in isolation, but inconsistencies, duplications, and architectural gaps accumulate across sessions without anyone consciously deciding to take a shortcut.

  2. Seven AI-specific debt patterns are predictable and identifiable. Style drift across sessions, copy-paste duplication, over-engineered solutions, hallucinated patterns that work, missing abstractions, shallow understanding debt, and dependency bloat appear in virtually every non-trivial AI-assisted project.

  3. You cannot manage debt you cannot see. Systematic identification through architectural reviews, static analysis tools, duplication detectors, and complexity metrics is the foundation of all debt management. Build and maintain a structured debt catalog.

  4. Measurement turns gut feelings into actionable data. Use the Technical Debt Ratio, cyclomatic complexity, cognitive complexity, pattern consistency scores, and duplication density to quantify debt. Track these metrics over time to reveal trends.

  5. Prioritize ruthlessly using the effort-impact matrix. Not all debt is equally urgent. Quick Wins (low effort, high impact) should be addressed first. Some debt (high effort, low impact) should be deliberately accepted. Security and data integrity debt always receive top priority.

  6. The same AI that creates debt can help fix it. AI excels at consistent refactoring across many files, extracting shared abstractions from duplicated code, and simplifying over-engineered solutions. Always verify AI remediation against your test suite.

  7. Prevention is cheaper than remediation. Project conventions documents, template files, review gates, pre-commit hooks, and well-maintained AI context dramatically reduce debt accumulation. Invest in these guardrails early.

  8. Use the decision framework to make deliberate debt choices. Check the decision tree: security issues are fixed immediately, trivial fixes are done now, blocking issues are scheduled for the current sprint, and other items are cataloged and reassessed quarterly.

  9. Communicate debt in business terms, not technical jargon. Stakeholders respond to velocity impact ("features take 30% longer"), risk ("known security gap in authentication"), and cost ("each new developer takes two extra weeks to onboard"), not to cyclomatic complexity scores.

  10. Allocate a debt budget of 10-20% of development capacity. This normalizes debt work as a routine part of development and prevents the debt backlog from growing unbounded.

  11. The Boy Scout Rule provides continuous improvement at no extra cost. Leaving code better than you found it — fixing one naming inconsistency, removing one unused import, adding one missing type hint — incrementally improves the most-touched areas of the codebase.

  12. Long-term codebase health requires ongoing discipline, not one-time efforts. Track metrics over time, review the debt catalog regularly, and treat the codebase as a product that your development team uses daily.

  13. When debt becomes unsustainable, you have three options. Aggressive remediation (50-80% of capacity for 1-3 months), selective rewrite (targeting the worst modules), or full rewrite (the nuclear option). All three require applying prevention lessons from the start.

  14. The best vibe coders optimize for long-term speed, not just short-term output. Code that is fast to understand, modify, debug, and extend remains productive for years. Code that was fast to generate but hard to maintain becomes a liability within months.