🏗️ Architectural Debt

Architectural Debt: Structural problems in the codebase that make it difficult to understand, modify, or extend. It arises when AI tools generate code that "works" but lacks clear boundaries, explicit interfaces, or a coherent modular design.

Characteristics

  • Code that functions correctly but has no discernible structure.
  • Changes in one module unexpectedly break logic in a distant, unrelated module.
  • Impossible to test individual components in isolation.
  • No clear "Separation of Concerns" (e.g., UI code mixed with database logic).
  • Spaghetti code resulting from layers of AI-generated "patches."

Examples

1. The Monolithic Prompt Result

AI tends to cram everything into a single file to keep the context simple. This results in 1,000+ line "God Files" that are impossible to maintain.

2. Hidden Dependencies

AI often generates code that assumes a specific global state or another module's internal structure without explicitly declaring it. These "invisible threads" make refactoring a nightmare.

3. Copy-Paste Architecture

Repeated patterns across the codebase that aren't abstracted into reusable functions. If a bug is found in one implementation, it must be manually fixed in ten other places.

Severity Levels

| Level | Description | Typical Remediation Cost | |-------|-------------|-------------------------| | 🔴 Critical | System cannot be extended without a complete rewrite. | $80,000+ | | 🟠 High | Major features require hacks and workarounds. | $20,000 - $40,000 | | 🟡 Medium | Development speed is visibly slowing down. | $4,000 - $8,000 | | 🟢 Low | Minor inconsistencies, manageable with discipline. | $800 - $1,600 |

Remediation Strategies

  1. Modularization: Break monoliths into clear, bounded modules with explicit APIs.
  2. Interface Contracts: Define clear "promises" between components to eliminate hidden dependencies.
  3. Refactoring Sprints: Dedicate 20% of every sprint to structural cleanup, not just feature generation.
  4. ADRs (Architectural Decision Records): Document why the structure exists to prevent future AI from breaking it.

Related Vibe-Code Smells

These smells are the primary contributors to Architectural Debt:

Book Reference

Architectural Debt is tracked throughout the TaskFlow case study:

  • Primary: Chapter 1, Chapter 5, and Chapter 7.
  • Remediation: Chapter 13 and Chapter 14.
  • Appendix A: Full debt catalog.

Stop building houses of cards

Get Clean Vibe Code