> "Technical debt is like financial debt. It's fine to take on debt to move faster — as long as you know the interest rate, track the balance, and have a payoff plan. The problem is, most teams have a pile of IOUs they can't even read."
Your codebase has technical debt. Everyone knows this. Nobody knows how much, what it costs, or when it becomes unsustainable.
Tech Debt Ledger applies double-entry bookkeeping to technical debt. Every shortcut, workaround, and "we'll fix it later" becomes a ledger entry with:
Not all tech debt is the same. Different types carry different interest rates:
| Debt Type | Principal | Interest Rate | Interest Type | Example |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| Prudent-Deliberate | Known, planned | Low (2-5%) | Simple | "Ship with manual deploy; automate later" |
| Prudent-Inadvertent | Discovered later | Medium (5-15%) | Simple | "Now we know we should have used X pattern" |
| Reckless-Deliberate | Known, ignored | High (15-30%) | Compound | "We don't have time for tests" |
| Reckless-Inadvertent | Unknown until crisis | Very High (30%+) | Compound | "What do you mean there's no input validation?" |
CURRENT COST = Principal + Accumulated Interest
Where:
Simple interest: Accumulated = Principal × Rate × Time
Compound interest: Accumulated = Principal × (1 + Rate)^Time - Principal
TOTAL DEBT BURDEN = Σ(Current Cost of all entries)
DEBT SERVICE RATIO = Monthly interest payments / Monthly development capacity
< 0.15 → Healthy
0.15-0.30 → Manageable (prioritize payoff)
0.30-0.50 → Stressed (debt is slowing you down)
> 0.50 → Crisis (most work is fighting debt, not building features)
Each debt entry is a complete financial instrument:
╔══════════════════════════════════════════════════════════════╗
║ DEBT ENTRY: #TD-2025-047 ║
╠══════════════════════════════════════════════════════════════╣
║ ║
║ DESCRIPTION: No integration tests for payment flow ║
║ LOCATION: src/payments/*, src/checkout/* ║
║ CATEGORY: Reckless-Deliberate ║
║ INCURRED: 2025-01-15 (Sprint 42, "launch deadline") ║
║ ║
║ PRINCIPAL: 16 dev-hours to write comprehensive ║
║ integration test suite ║
║ ║
║ INTEREST RATE: 20% per quarter (compound) ║
║ INTEREST TYPE: Compound — untested code attracts more ║
║ untested code; complexity grows ║
║ ║
║ CURRENT BALANCE: 23.1 dev-hours (7.1h interest accrued) ║
║ ║
║ MINIMUM PAYMENT: 2 dev-hours/month ║
║ (manual testing each deploy, ║
║ investigating payment bugs) ║
║ ║
║ MATURITY DATE: 2025-07-01 (EU compliance audit) ║
║ MATURITY PENALTY: Compliance failure, potential fine ║
║ ║
║ INTEREST EXPLANATION: ║
║ Every month without tests, the payment code changes. ║
║ Each change makes the eventual test suite harder to write. ║
║ Developers avoid refactoring because there's no safety net. ║
║ Bad patterns calcify. The 16-hour fix today becomes a ║
║ 40-hour fix in 6 months. ║
╚══════════════════════════════════════════════════════════════╝
| Rating | Debt-to-Capacity Ratio | Translation |
|---|---|---|
| --- | --- | --- |
| AAA | < 5% | Minimal debt, healthy codebase |
| AA | 5-10% | Low debt, well-managed |
| A | 10-20% | Moderate debt, payoff plan needed |
| BBB | 20-30% | Significant debt, slowing development |
| BB | 30-40% | High debt, feature velocity declining |
| B | 40-50% | Severe debt, most work is maintenance |
| CCC | 50-70% | Distressed, rewrite being discussed |
| D | > 70% | Default, codebase is effectively unmaintainable |
DEBT HEATMAP:
├── src/payments/ ████████████████████ 42h (36% of total debt)
├── src/auth/ ████████████ 24h (21%)
├── src/checkout/ ████████ 18h (15%)
├── src/api/ ██████ 14h (12%)
├── src/utils/ ████ 9h (8%)
└── src/ui/ ████ 9h (8%)
Total: 116 dev-hours
AUTOMATED DISCOVERY:
├── TODO/FIXME/HACK/WORKAROUND comments → convert to ledger entries
├── Code complexity hotspots → potential structural debt
├── Test coverage gaps → testing debt
├── Outdated dependencies → maintenance debt
├── Copy-pasted code → duplication debt
├── Dead code / unused exports → cleanliness debt
├── Missing error handling → reliability debt
└── Hardcoded values → configuration debt
MANUAL DISCOVERY:
├── "We know this is wrong but..." decisions
├── Shortcuts taken for deadlines
├── Deferred refactoring
├── Missing documentation
└── Known security gaps
FOR EACH ITEM:
├── Estimate fix time (optimistic, realistic, pessimistic)
│ └── Principal = realistic estimate
├── Estimate interest rate:
│ ├── Does this area change frequently? (high change = high interest)
│ ├── Do bugs cluster here? (high bugs = high interest)
│ ├── Does this block other work? (blocking = high interest)
│ └── Does this have a deadline? (deadline = maturity date)
├── Classify interest type:
│ ├── Simple: cost grows linearly (tech stays the same)
│ └── Compound: cost grows exponentially (complexity breeds complexity)
└── Set minimum payment: ongoing maintenance cost to keep it alive
| Strategy | Description | Best For |
|---|---|---|
| --- | --- | --- |
| Avalanche | Pay highest interest rate first | Maximum long-term savings |
| Snowball | Pay smallest principal first | Quick wins, team morale |
| Targeted | Pay debts blocking specific goals | Deadline-driven projects |
| Minimum | Pay only minimum payments | When feature work is critical |
| Refinance | Replace expensive debt with cheaper debt (e.g., swap hack with simpler hack) | When full fix isn't feasible |
QUARTERLY DEBT BUDGET:
├── Total development capacity: 480 dev-hours
├── Feature work allocation: 384 dev-hours (80%)
├── Debt payoff allocation: 96 dev-hours (20%)
│
├── PAYOFF PLAN (Avalanche strategy):
│ ├── #TD-2025-047: Payment tests (16h principal, 20% interest) → PAY IN FULL
│ ├── #TD-2025-023: Auth refactor (24h principal, 15% interest) → PAY IN FULL
│ ├── #TD-2025-031: API versioning (18h principal, 10% interest) → PAY IN FULL
│ └── #TD-2024-089: Legacy utils (38h principal, 8% interest) → PARTIAL (38h remaining)
│
├── PROJECTED BALANCE AFTER QUARTER:
│ ├── Before: 116 dev-hours
│ ├── Paid off: 58 dev-hours
│ ├── New interest on remaining: 4.2 dev-hours
│ └── After: 62.2 dev-hours
│
└── DEBT RATING CHANGE: BBB → A (improvement)
╔══════════════════════════════════════════════════════════════╗
║ TECH DEBT LEDGER ║
║ Balance Sheet — Q1 2025 ║
╠══════════════════════════════════════════════════════════════╣
║ ║
║ TOTAL DEBT BALANCE: 116 dev-hours ║
║ DEBT RATING: BBB (Significant) ║
║ DEBT SERVICE RATIO: 0.23 (Manageable) ║
║ MONTHLY INTEREST ACCRUAL: 8.4 dev-hours ║
║ MONTHLY MINIMUM PAYMENT: 12 dev-hours ║
║ ║
║ TOP 5 DEBTS BY INTEREST COST: ║
║ # | Description | Balance | Rate | Monthly $ ║
║ ───┼──────────────────────────┼─────────┼──────┼────────── ║
║ 1 | No payment tests | 23.1h | 20% | 1.5h/mo ║
║ 2 | Auth module no types | 28.8h | 15% | 1.1h/mo ║
║ 3 | Hardcoded config values | 12.0h | 12% | 0.5h/mo ║
║ 4 | No API versioning | 21.6h | 10% | 0.7h/mo ║
║ 5 | Legacy utility functions | 42.0h | 8% | 1.1h/mo ║
║ ║
║ TREND: ║
║ ├── Last quarter: 94h → This quarter: 116h (+23%) ║
║ ├── New debt incurred: 31h ║
║ ├── Debt paid off: 17h ║
║ └── Interest accrued: 8.4h ║
║ ║
║ ⚠ ALERT: Debt is growing faster than payoff. ║
║ At current rate, balance reaches 180h in 6 months. ║
║ Recommend: Increase payoff allocation from 15% to 25%. ║
╚══════════════════════════════════════════════════════════════╝
Teams that track tech debt as a vague "we should fix that" never fix it. Teams that track it as quantified financial obligations make rational decisions about when to pay, how much to pay, and which debts to accept.
The goal isn't zero debt. The goal is informed debt — knowing exactly what you owe, what it costs, and having a plan.
Zero external dependencies. Zero API calls. Pure estimation and tracking.
共 1 个版本