Originally written in French. Translated by AI — the meaning has been preserved, not the prose.
Short definition
The gap between what a system does and what the team answering for it can explain. It is contracted every time code is accepted without anyone being able to say why it is written that way, and it is repaid in time spent reconstructing an intention nobody ever formed.
Full definition
The phrase is modelled on technical debt, whose mechanics it takes up — an immediate advantage obtained against an increased future cost — while changing what is borrowed. Technical debt bears on the state of the code; this one bears on the state of the heads of those who maintain it.
In the articles on this blog, the term designates the counterpart of assisted development: a team that merges generated code, accepted and patched without anyone being able to explain it, gets functionality straight away and an inability to diagnose later. The liability is invisible as long as nothing breaks, since the application runs, the screens respond and the tests pass.
The normative sense would want a debt that is measurable and repayable through an identified project. Field usage knows neither counter nor due date: it is observed at the moment of the incident, when a team discovers it no longer knows why everything is collapsing, and its repayment goes through a rereading nobody has time to undertake any more.
Usage in the field
The term comes into play in merge rules — refusing code nobody can explain — in arbitrating the budget of understanding per feature (the contract, the tests, the architecture decision, the known limits), and in diagnosing a team whose rate of fixing rises without the product changing.
Synonyms and variants
"Un-understood code", "accepting code you can't explain". Neighbouring turns of phrase used for the same liability: "a system nobody ever inhabited", "an architecture whose decisions nobody took".
Not to be confused with
- Technical debt — a design weakness the company has decided will be handled, and which on that count carries a cost and a place in the priorities; it is repaid in rebuilding work, where understanding debt is paid in an inability to decide what to rebuild — and it waits for a decision in order to exist, whereas this one is contracted at the merge.
- Reconstructibility — the property of a system a team would know how to rebuild elsewhere; it is the asset this debt is the liability of, and the question "would I know how to rebuild it?" is the most direct way of observing either one.
- Documentation debt — the absence or obsolescence of the documents describing the system; a team can have documented everything and understand nothing, just as it can understand everything without having written anything.
- Bus factor — the number of people whose departure would make a system unworkable; it measures the distribution of an understanding that exists, not its absence.
- Legacy — an inherited system whose decisions were taken elsewhere and earlier; understanding debt accumulates on code written this week.
Examples
"If a team accepts code it doesn't understand, it accepts understanding debt." — the reference usage, posited as the consequence of a merge rule.
Dozens of pull requests created overnight by an assistant and merged without anyone having checked the impacts: the volume shipped is liability, not a head start.
An application that passes the happy paths and contains hundreds of generated technical choices, accepted, patched then forgotten, carries the whole debt, even if no defect has yet appeared.
Ambiguities / debates
The word "debt" suggests an amount and a due date that nothing here allows you to establish: no attested practice puts a number on the gap between what a system does and what a team explains about it.
Attribution stays debated: is the debt carried by the person who merged, or by the team that maintains? The usage retained here places it on the team, since the team is what repays it.