12 KiB
name, description
| name | description |
|---|---|
| engineering-technical-debt | Identifying, measuring, tracking, and managing technical debt strategically and systematically |
Technical Debt Management
Scope: Comprehensive guide to identifying, measuring, prioritizing, and paying down technical debt Lines: ~320 Last Updated: 2025-10-27 Format Version: 1.0 (Atomic)
When to Use This Skill
Activate this skill when:
- Evaluating whether to take on technical shortcuts
- Prioritizing refactoring vs new features
- Explaining tech debt costs to stakeholders
- Planning debt paydown sprints
- Auditing codebase health
- Establishing tech debt policies
- Preventing debt accumulation
- Recovering from tech debt crisis
Core Concepts
Concept 1: What is Technical Debt?
Definition: Code shortcuts that speed up delivery but increase future maintenance costs
Martin Fowler's Quadrant:
Reckless Prudent
Deliberate | "We don't have | "We must ship now,
| time for | will refactor later"
| design" |
-------------|----------------|------------------
Inadvertent | "What's | "Now we know how
| layering?" | we should have
| | done it"
Types of Tech Debt:
- Code Debt: Poor code quality, duplication, smells
- Design Debt: Wrong abstractions, tight coupling
- Test Debt: Missing tests, brittle tests
- Documentation Debt: Outdated or missing docs
- Infrastructure Debt: Outdated dependencies, poor tooling
- Architecture Debt: Scaling issues, monolith problems
Concept 2: Interest vs Principal
Like Financial Debt:
- Principal: Cost to fix the issue
- Interest: Ongoing cost of living with it
# Example: Duplicated validation logic (Principal: 1 day to refactor)
# File 1
def create_user(email):
if "@" not in email: # Duplicated
raise ValueError("Invalid email")
# ... save user
# File 2
def update_user(email):
if "@" not in email: # Duplicated
raise ValueError("Invalid email")
# ... update user
# File 3
def invite_user(email):
if "@" not in email: # Duplicated
raise ValueError("Invalid email")
# ... send invite
# Interest paid:
# - Every bug fix needs 3 changes
# - Every validation enhancement needs 3 updates
# - Risk of inconsistency
# - Slows down all email-related features
Concept 3: When to Take On Debt
Good Reasons (Deliberate, Prudent):
- MVP to validate market fit
- Time-sensitive opportunity
- Competitive pressure
- Known paydown plan
Bad Reasons (Reckless):
- Laziness or lack of skill
- "We'll never come back to this"
- No plan to pay down
- Not understanding implications
Patterns
Pattern 1: Debt Identification
Code Smells Checklist:
[ ] Duplicated code (copy-paste)
[ ] Long methods (> 30 lines)
[ ] Large classes (> 500 lines)
[ ] Long parameter lists (> 4 params)
[ ] Divergent change (class changes for multiple reasons)
[ ] Shotgun surgery (one change affects many classes)
[ ] Feature envy (method uses another class more than its own)
[ ] Data clumps (same group of data everywhere)
[ ] Primitive obsession (over-reliance on primitives)
[ ] Comments explaining complex code
Automated Detection:
# Python: Code complexity
radon cc src/ -a -nb # Cyclomatic complexity
radon mi src/ # Maintainability index
# JavaScript: ESLint complexity rules
eslint --max-complexity=10 src/
# Code duplication
jscpd src/ # Copy-paste detector
# Security debt
npm audit
pip-audit
Pattern 2: Debt Measurement
Debt Score Formula:
Debt Score = (Complexity × Impact × Frequency) / Ease of Fix
Complexity: 1-5 (how complex is the problem?)
Impact: 1-5 (how many people/systems affected?)
Frequency: 1-5 (how often is this code touched?)
Ease of Fix: 1-5 (how easy to fix?)
Example Scoring:
# Debt Item: Duplicated email validation (3 places)
Complexity = 2 # Simple validation logic
Impact = 4 # Used in 10+ features
Frequency = 5 # Changed weekly
Ease of Fix = 4 # Easy - extract to function
Debt Score = (2 × 4 × 5) / 4 = 10
# Debt Item: Monolithic architecture
Complexity = 5 # Very complex to split
Impact = 5 # Affects entire system
Frequency = 3 # Changes monthly
Ease of Fix = 1 # Very difficult
Debt Score = (5 × 5 × 3) / 1 = 75 # High priority!
Pattern 3: Debt Tracking
Debt Register (track in TECH_DEBT.md):
# Technical Debt Register
## High Priority (Score > 50)
### TD-001: Monolithic Database
- **Debt Score**: 75
- **Principal**: 4 weeks
- **Interest**: 1 day/week (slow queries, deployment bottleneck)
- **Paydown Plan**: Split into microservices over Q2
- **Status**: Planned
## Medium Priority (Score 20-50)
### TD-002: Missing Integration Tests
- **Debt Score**: 30
- **Principal**: 2 weeks
- **Interest**: 2 hours/week (manual testing)
- **Paydown Plan**: Add tests incrementally with each feature
- **Status**: In Progress
## Low Priority (Score < 20)
### TD-003: Outdated Dependencies
- **Debt Score**: 12
- **Principal**: 1 day
- **Interest**: 30 min/month (security patches)
- **Paydown Plan**: Update in Q3 maintenance sprint
- **Status**: Backlog
Pattern 4: Debt Paydown Strategies
Boy Scout Rule: Leave code better than you found it
# Every PR: Small improvements
# Before
def process_user(email, name, age, address, phone): # Too many params
# ... 50 lines of code
# After (in PR for unrelated feature)
class UserData:
def __init__(self, email, name, age, address, phone):
self.email = email
self.name = name
# ...
def process_user(user_data: UserData): # Better!
# ... same logic
Debt Sprints: Dedicated time to pay down debt
Sprint 10: Features (80%) + Debt (20%)
- Feature: User dashboard
- Debt: Extract shared validation logic
Sprint 11: Features (80%) + Debt (20%)
- Feature: Payment integration
- Debt: Add integration tests for auth
Sprint 15: Debt Sprint (100%)
- Upgrade all dependencies
- Refactor monolithic service
- Add missing documentation
Strangler Fig Pattern: Gradually replace old system
1. Identify module to replace
2. Build new implementation alongside old
3. Route new requests to new code
4. Migrate existing data gradually
5. Remove old code when fully migrated
Example:
┌─────────────────┐
│ Old Auth System │ ←─┐
└─────────────────┘ │
├─ Route new users to new system
┌─────────────────┐ │ Migrate old users gradually
│ New Auth System │ ←─┘
└─────────────────┘
Pattern 5: Preventing Debt
Definition of Done (include quality checks):
## Definition of Done
Code Complete:
- [ ] Feature implemented
- [ ] Unit tests written (80%+ coverage)
- [ ] Integration tests added
- [ ] Documentation updated
- [ ] Code reviewed
- [ ] No TODO/FIXME comments (create tickets instead)
- [ ] No copy-paste code
- [ ] Cyclomatic complexity < 10
- [ ] No security vulnerabilities
Pre-Commit Hooks:
# .pre-commit-config.yaml
repos:
- repo: https://github.com/psf/black
hooks:
- id: black # Formatting
- repo: https://github.com/pycqa/flake8
hooks:
- id: flake8 # Linting
args: [--max-complexity=10]
- repo: https://github.com/pre-commit/mirrors-mypy
hooks:
- id: mypy # Type checking
Quality Gates in CI:
# .github/workflows/quality.yml
- name: Check code quality
run: |
radon cc src/ -a -nb --total-average-threshold=B
radon mi src/ --min=C
- name: Check test coverage
run: |
pytest --cov=src --cov-fail-under=80
- name: Check for code duplication
run: |
jscpd src/ --threshold 5 # Fail if > 5% duplication
Debt Communication
Explaining to Stakeholders
Avoid: "We have technical debt" (vague, no context)
Better: Use analogies and business impact
"Our authentication system is like a house built without a foundation.
It works today, but:
- Every new feature takes 2x longer to build
- Security fixes require changes in 5 different places
- We have 3 critical bugs per month due to inconsistency
Investment: 2 weeks to refactor
Payoff: 50% faster feature development, 90% fewer auth bugs
ROI: Pays for itself in 2 months"
Debt Dashboard (visualize for stakeholders):
Tech Debt Metrics Dashboard
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total Debt: 12 weeks
Interest Cost: 8 hours/week
High Priority Debt: [██████----] 60%
Test Coverage: [████------] 45%
Code Duplication: [██████----] 15%
Complexity: [████████--] 80%
Trend: ↑ Increasing (action needed!)
Best Practices
Debt Management Guidelines
Do's:
- Track debt explicitly (don't hide it)
- Measure debt objectively
- Pay down incrementally
- Prevent new debt
- Communicate impact to stakeholders
- Schedule regular debt sprints
- Use automated tools
Don'ts:
- Don't ignore growing debt
- Don't pay all debt at once (balance with features)
- Don't blame individuals
- Don't take on debt without plan
- Don't use "tech debt" as excuse for poor work
- Don't let debt compound
Anti-Patterns
Common Debt Management Mistakes
❌ "We'll fix it later" (Never happens)
→ Fix now or create explicit paydown plan
❌ Ignoring debt until crisis
→ Track and pay down incrementally
❌ Only paying principal, ignoring interest
→ Prioritize high-interest debt first
❌ 100% features, 0% debt paydown
→ Allocate 20% of sprint to debt
❌ Rewriting from scratch
→ Refactor incrementally (strangler fig)
❌ Not measuring debt
→ Quantify to prioritize effectively
❌ Debt as excuse for poor quality
→ Deliberate, prudent debt only
Decision Framework
Should We Take On This Debt?
IF time_pressure AND short_term_need AND have_paydown_plan:
TAKE_ON_DEBT
DOCUMENT(why, when_fix, cost)
SCHEDULE_PAYDOWN
ELSE:
DO_IT_RIGHT
Example Decision Matrix:
| Situation | Take Debt? | Condition |
|---|---|---|
| MVP launch | ✅ Yes | Must have paydown plan |
| Competitive threat | ✅ Yes | Document & schedule fix |
| Learning new tech | ✅ Yes | First time doing X |
| Lack of skill | ❌ No | Learn or ask for help |
| Laziness | ❌ No | Do it right |
| No plan to fix | ❌ No | Schedule paydown or don't ship |
Code Examples
Before (High Debt):
# Duplicated validation everywhere
def create_user(email, password):
if not email or "@" not in email:
raise ValueError("Invalid email")
if len(password) < 8:
raise ValueError("Password too short")
# ... create user
def update_email(user_id, email):
if not email or "@" not in email: # Duplicated!
raise ValueError("Invalid email")
# ... update email
def send_invite(email):
if not email or "@" not in email: # Duplicated!
raise ValueError("Invalid email")
# ... send invite
After (Debt Paid):
# Extracted validation (DRY)
class EmailValidator:
@staticmethod
def validate(email: str) -> None:
if not email or "@" not in email:
raise ValueError("Invalid email")
class PasswordValidator:
@staticmethod
def validate(password: str) -> None:
if len(password) < 8:
raise ValueError("Password too short")
def create_user(email, password):
EmailValidator.validate(email)
PasswordValidator.validate(password)
# ... create user
def update_email(user_id, email):
EmailValidator.validate(email)
# ... update email
def send_invite(email):
EmailValidator.validate(email)
# ... send invite
Related Skills
- engineering-refactoring-patterns: Techniques for paying down debt
- engineering-code-quality: Preventing debt through quality
- engineering-code-review: Catching debt in reviews
- engineering-test-driven-development: Preventing test debt
- engineering-continuous-integration: Automated debt detection