4 min lectura • Guide 245 of 877
How to Track Technical Debt in Agile Projects
Technical debt becomes unmanageable when it's invisible. GitScrum makes debt trackable with dedicated labels, a debt backlog visible alongside features, and sprint allocation strategies that ensure you're paying down debt incrementally rather than letting it compound.
Why Debt Tracking Matters
The Hidden Cost of Invisible Debt
TECHNICAL DEBT PROBLEMS:
┌─────────────────────────────────────────────────────────────┐
│ WHAT HAPPENS WITHOUT TRACKING │
├─────────────────────────────────────────────────────────────┤
│ │
│ ❌ INVISIBLE DEBT: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ • "We'll clean this up later" → never happens ││
│ │ • No one knows the total debt load ││
│ │ • New features take longer (fighting old code) ││
│ │ • Developer frustration grows ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ ❌ DEBT AVALANCHE: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ • Small debts compound into large problems ││
│ │ • Eventually requires "stop the world" refactor ││
│ │ • Features delayed for emergency cleanup ││
│ │ • Could have been prevented with incremental work ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ ❌ STAKEHOLDER DISCONNECT: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ • "Why is development slowing down?" ││
│ │ • No data to justify refactoring time ││
│ │ • Technical work seen as avoiding "real" features ││
│ │ • Debt work not valued in planning ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
Debt Tracking System
GitScrum Debt Organization
| Label | Description | Priority |
|---|---|---|
| tech-debt:critical | Blocks other work | Sprint immediately |
| tech-debt:high | Slows development | Next 2 sprints |
| tech-debt:medium | Should fix eventually | Quarterly |
| tech-debt:low | Nice to have cleanup | Opportunistic |
Debt Management Workflow
Making Debt Visible and Actionable
TECHNICAL DEBT WORKFLOW:
┌─────────────────────────────────────────────────────────────┐
│ FROM DISCOVERY TO RESOLUTION │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. CAPTURE WHEN DISCOVERED: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ • Developer notices debt while working ││
│ │ • Create task immediately (takes 2 min) ││
│ │ • Add tech-debt label with severity ││
│ │ • Describe: what, where, why it matters ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ 2. TRIAGE REGULARLY: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ • Weekly: Review new debt items ││
│ │ • Validate severity labels ││
│ │ • Estimate effort (story points) ││
│ │ • Link related debt items ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ 3. ALLOCATE TO SPRINTS: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Rule of thumb: ││
│ │ • 10-20% of sprint capacity for debt ││
│ │ • Critical debt: mandatory, no negotiation ││
│ │ • High debt: plan for next 2-3 sprints ││
│ │ • Opportunistic: bundle with related features ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ 4. TRACK PROGRESS: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ • Filter board by tech-debt labels ││
│ │ • Monitor debt backlog size over time ││
│ │ • Celebrate debt paydown in retros ││
│ │ • Adjust allocation if debt grows ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
Measuring Debt Health
Metrics to Track
| Metric | Target | What It Shows |
|---|---|---|
| Debt item count | Stable or decreasing | Backlog health |
| Critical debt age | < 2 sprints | Urgency response |
| Sprint debt % | 10-20% | Investment level |
| New vs resolved | Resolved > New | Progress trend |