What is a Debt Unit?
Debt Unit: The standardized unit of measurement in the Clean Vibe methodology. It allows teams to quantify Synthetic Debtβmaking invisible risks comparable and manageable.
The Severity Scale
In Clean Vibe Code, we categorize debt items into four levels of severity:
- π΄ Critical (10 Units): Production-breaking risks, active security vulnerabilities, or core IP with zero comprehension. Immediate attention required.
- π High (5 Units): Major architectural violations, Magic Black Boxes in critical paths, or significant IP vacuum.
- π‘ Medium (2 Units): Inconsistent patterns (Style Drift), missing ADRs for minor features, or token waste.
- π’ Low (1 Unit): Minor documentation gaps or "temporary" code that is well-understood.
The Debt Formula
Units = Ξ£(Sev Γ Count)
Total Debt Load Formula
100 Units
Threshold for Project Crisis
By summing the units in your Debt Ledger, you can calculate your project's Total Debt Load. This provides a clear, data-driven signal for when to stop feature development and start refactoring.
Why Quantify Debt?
- Objectivity: Moves the conversation from "it feels messy" to "we have 45 units of high-risk debt."
- Prioritization: Helps developers decide which "Magic Black Box" to refactor first.
- Business Alignment: Allows engineering leads to explain technical risk to founders and investors using data.
Related Terms
- Debt Ledger: Where units are recorded.
- Debt Budget: How units are managed per sprint.
- Synthetic Debt: What the units measure.
Book Reference
- Appendix A: Full catalog of debt categories with assigned unit values.
- Chapter 10: The Audit β how to perform a full debt unit accounting.