- Description
- Chantier de construction enserré dans d'énormes échafaudages, avec grues et conteneurs de matériaux.
- Source
- Fons Heijnsbroek · original page
- Licence
- CC0 Public domain
Technical Debt and Maintainability
This theme measures the ability to keep software modifiable over time: technical debt is known, quantified, prioritized, and repaid at a chosen pace rather than endured. The promise…
In brief
This theme measures the ability to keep software modifiable over time: technical debt is known, quantified, prioritized, and repaid at a chosen pace rather than endured. The promise is not “zero debt” (conscious debt is a tool) but “debt does not slow down the team without them knowing it.”
Level: 🟢→🔴 · Theme code: DTT (DL matrix)
Why this theme#
The debt metaphor comes from Ward Cunningham: taking a shortcut to deliver earlier is borrowing; as long as you do not repay, you pay interest (every change is slower). Martin Fowler distinguished deliberate debt from accidental debt, reckless debt from prudent debt. The main danger is invisible debt: no one measures it, so the cost appears as “velocity dropping” with no explanation, or as an inability to recruit (no one wants to touch that code).
Debt is not limited to code: dependencies and platforms reaching end of support, database schemas that have become incomprehensible, incorrect documentation, fragile pipelines, scripts with a single author, slow tests. In a product that maintains multiple versions in parallel, each supported version is debt: it multiplies fixes. See 04.
What the theme measures#
- Axis: from “we endure it” to “debt is a managed portfolio, with a repayment budget.”
- Key indicators: share of capacity dedicated to repayment (%) ; lead time for a typical change (trend) ; share of components at end of support ; age of recognized debt.
- Unit: % of capacity ; days ; number of items, age.
Five-level table#
| Level | Short name | Promise | Typical indicator (orders of magnitude) |
|---|---|---|---|
| 1 | Endured | We do not know why changes are slowing down. | No list ; repayment ≈ 0% |
| 2 | Recognized | Known debt is recorded, and everyone can cite the main items. | Debt register ; opportunistic repayment |
| 3 | Prioritized | Each debt item has an estimated cost and a dated decision (repay, accept, retire). | Prioritized register ; 10-20% of capacity reserved |
| 4 | Measured | The change-cost trend is tracked ; repayment is steered by observed impact. | Lead time for a typical change tracked ; debt decreases at constant scope |
| 5 | Sustainable | Debt taken on is intentional, bounded, and repaid before due date ; the product remains easy to change after ten years. | No unsupported component ; stable change lead time for 3 years |
Milestones by level#
| ID | Milestone | Verifiable evidence |
|---|---|---|
| DL-DTT-1.1 | The team can identify the 3 riskiest areas to modify | Converging answers from three people |
| DL-DTT-1.2 | Shortcuts taken are flagged when they are taken (comment, ticket) | At least 5 items flagged |
| DL-DTT-1.3 | Used components and versions are known | Inventory |
| DL-DTT-2.1 | A debt register exists (item, type, origin, consequence) | Accessible, dated register |
| DL-DTT-2.2 | Components reaching end of support are listed with their date | “End of support” column |
| DL-DTT-2.3 | Debt items are linked to components and owners | Named owner per item |
| DL-DTT-2.4 | Documentation and testing debt is distinguished from code debt | Categories in the register |
| DL-DTT-3.1 | Each item is estimated in interest cost (days lost per month) and repayment cost | Estimates, even rough ones |
| DL-DTT-3.2 | A fixed share of capacity (for example 10 to 20%) is reserved for repayment | Planning across 3 iterations |
| DL-DTT-3.3 | Every new deliberate debt item gets a due date and an owner | Review of 10 recent shortcuts |
| DL-DTT-3.4 | The register is reviewed at regular intervals (at least quarterly) | Review minutes |
| DL-DTT-3.5 | “Accept debt” decisions are explicit and justified | Entry in the register |
| DL-DTT-4.1 | Lead time for a typical change (by component) is measured and its trend tracked | 12-month curve |
| DL-DTT-4.2 | High-change/high-debt areas (“hotspots”) are identified through change history | Historical analysis + complexity |
| DL-DTT-4.3 | Repayments are evaluated afterward (did change lead time drop?) | Impact review on 5 repayments |
| DL-DTT-4.4 | Dependency debt is tracked (version age, gap to latest stable) | Dependency age table |
| DL-DTT-4.5 | Supported versions and end-of-life policy are defined and published | Dated policy |
| DL-DTT-5.1 | No component remains at end of support without a quantified plan | Migration plan for each case |
| DL-DTT-5.2 | Debt is capped by policy: beyond a threshold, delivery of new features slows down | Freeze decision already applied |
| DL-DTT-5.3 | Major replacements are incremental and continuously funded, not a “big bang” | History of the last 3 migrations |
| DL-DTT-5.4 | A newcomer modifies the oldest areas without heavy support | Onboarding measured on older areas |
Detailed reading by level#
🟢 Level 1 — Endured#
- Signs: “we do not have time to clean up” ; taboo areas ; estimates get inflated.
- Gain: fast short-term delivery.
- Does not guarantee: sustainability ; interest accumulates silently.
- Difficulty: 1/5 · Effort: 1/5.
🟢 Level 2 — Recognized#
- Signs: a register, an end-of-support list, a few owners.
- Gain: debt is no longer taboo.
- Does not guarantee: that it is repaid: a register can become a graveyard of good intentions.
- Difficulty: 2/5 · Effort: 1/5.
🟡 Level 3 — Prioritized#
- Signs: a reserved share of capacity ; every deliberate shortcut has a due date. Discussions with the business go through interest cost (“this area costs us 4 days per month”) rather than code aesthetics.
- Gain: explicit, defensible trade-offs.
- Does not guarantee: that estimates are accurate — they are orders of magnitude.
- Difficulty: 3/5 · Effort: 3/5.
🔴 Level 4 — Measured#
- Signs: lead time for a typical change is tracked, hotspots are identified (files that change often and are complex), and after repayment it is verified that cost went down.
- Gain: investment goes where it pays off.
- Does not guarantee: prevention of new debt ; upstream discipline is also needed (02).
- Difficulty: 4/5 · Effort: 4/5.
🔴 Level 5 — Sustainable#
- Signs: debt is capped, continuously funded, and major migrations are done incrementally. The product ages without freezing.
- Gain: durability, code attractiveness for hiring.
- Does not guarantee: the absence of hard choices — one extra supported version is still a burden.
- Difficulty: 5/5 · Effort: 5/5.
Partial achievement and rating#
Apply the rating rule.
- 0.5 on DL-DTT-3.2: capacity is reserved, but only when “there is no emergency.”
- 0.5 on DL-DTT-4.1: change lead time is measured on one component only.
- A partial 5: debt cap decided, never triggered yet ; incremental migrations on only one workstream.
Graveyard register. Symptom: 400 items, none addressed. Cause: no cost estimation or threshold. Remedy: only record items with an interest cost, close what has no future.
Big bang. Symptom: “we will rewrite everything, 18 months.” Cause: debt perceived as unsustainable. Remedy: progressive strangulation (01), value delivery at each step.
Cross-reference change frequency and complexity: a complex but stable area costs little, a simple but very fast-changing area costs little — it is the intersection that hurts. Repay there.
Datamart: one 1,200-line procedure, modified 14 times in one year, each change taking 3 days. Interest cost ≈ 42 days/year. An 8-day refactoring brings each change down to 1 day: the investment (8 days) pays back in under four months (28 days gained per year).
If you steer by the “number of debt items,” people merge or split them to lower the number. Steer by change lead time.
Moving to the next level#
Possible means (optional)
- 1 → 2: a one-hour workshop to list feared areas ; a simple register.
- 2 → 3: interest estimation, capacity reservation, due dates on shortcuts.
- 3 → 4: change lead time measurement, hotspot analysis, impact review after repayment.
- 4 → 5: debt cap, end-of-support plan, incremental migrations.
See also#
- Related themes: 01 Architecture · 02 Code Quality · 03 Testing · 10 Documentation · 12 Developer Experience.
- Other matrices: Project — Risk Management · Project — Continuous Improvement and Learning (AMC) · BI — Semantic Model.
- Practice: Pitfalls and Good Practices in Project Management (Cross-Functional Synthesis) · Comparison of Project Management Methods · Branching Strategies.
- Glossary · Rating: Reading Ratings, Scores, and the Legend.
✻ Written by Claude Sonnet 5.5
