2.2 KiB
2.2 KiB
Technical Debt
Debt Categories
| Type | Example | Urgency |
|---|---|---|
| Deliberate-Prudent | "Ship now, refactor next sprint" | Planned paydown |
| Deliberate-Reckless | "We don't have time for tests" | Accumulating risk |
| Inadvertent-Prudent | "Now we know a better way" | Normal learning |
| Inadvertent-Reckless | "What's layering?" | Learning curve |
When to Pay Down Debt
Pay now when:
- Debt is in path of upcoming work
- Cognitive load slowing every change
- Bugs recurring in same area
- Onboarding time increasing
Defer when:
- Area is stable, rarely touched
- Bigger refactor coming anyway
- Time constrained on priority work
- Code may be deprecated
ROI Framework
Debt ROI = (Time Saved Per Touch x Touches/Month x Months) / Paydown Cost
| ROI | Action |
|---|---|
| >3x | Prioritize immediately |
| 1-3x | Plan into upcoming work |
| <1x | Accept or isolate |
Refactoring Strategies
Strangler Fig
- Build new alongside old
- Redirect traffic incrementally
- Remove old when empty
Best for: Large system replacements
Branch by Abstraction
- Create abstraction over old code
- Implement new behind abstraction
- Switch implementations
- Remove old
Best for: Library/dependency swaps
Parallel Change (Expand-Contract)
- Add new behavior alongside old
- Migrate callers incrementally
- Remove old behavior
Best for: API changes
Mikado Method
- Try the change
- When it breaks, note prerequisites
- Revert
- Recursively fix prerequisites
- Apply original change
Best for: Untangling dependencies
Tracking Debt
Minimum viable debt tracking:
## Tech Debt Log
| ID | Description | Impact | Area | Added |
|----|-------------|--------|------|-------|
| TD-1 | No caching layer | Slow queries | /api | 2024-01 |
Review monthly. Prune resolved items.
Communicating Debt to Stakeholders
Frame as investment, not cleanup:
- "This will reduce bug rate by ~30%"
- "Deployment time goes from 2 hours to 20 minutes"
- "New features in this area take 2x longer than they should"
Avoid:
- "The code is messy"
- "We need to refactor"
- Technical jargon without business impact