Technical debt as a business decision — how to document architecture choices with ADRs

"Technical debt" has become a phrase developers use when something is messy, and that management hears as an excuse. That is a shame, because the metaphor is precise, and it was made for exactly that conversation. Ward Cunningham introduced it in 1992 to explain to the business why code has to be rewritten as you learn more: you borrow time now and pay it back later, with interest.

This post is about treating technical debt as what it is, a business decision, and about a lightweight tool for documenting it: Architecture Decision Records. The example uses the fictitious company Space Travel.

Debt is a choice that carries interest

Debt is not bad in itself. A loan can be the best decision a company makes, if it makes something possible that otherwise could not be done. The same goes for code. Releasing a simpler solution before a trade fair, a launch or a competitor can be exactly the right thing.

The problem is debt nobody knows they have taken on. Martin Fowler has described the difference along two axes: is the debt deliberate or inadvertent, and is it prudent or reckless? Deliberate, prudent debt sounds like this: "We release now and know what it will cost to clean up." Inadvertent debt is only discovered when the interest has already been paid in slower development, more bugs and developers who do not dare touch certain parts of the code.

The interest is what makes debt a business question. Every time someone has to change that part of the system, it costs extra time. The more often that part changes, the higher the interest. Debt in code that is never touched costs almost nothing. Debt at the core of the product costs every week.

Architecture Decision Records

An Architecture Decision Record, an ADR, is a short document about one important decision. The format was popularized by Michael Nygard in 2011 and typically consists of:

• Title and number, so the decision can be referred to.
• Status: proposed, accepted, superseded by a later ADR.
• Context: the situation and the forces pulling in different directions. This is the most important part, and the one most often forgotten.
• Decision: what we do, written in the active voice.
• Consequences: what becomes easier, what becomes harder, and which debt we deliberately take on.

ADRs are best kept in the repository, for example in docs/architecture/adr/, next to the code they are about. They are reviewed in the same pull request as the change, and they are not edited afterwards: if the decision changes, a new ADR is written that supersedes the old one. That way the history shows both what was decided and why it once made sense.

A template can be as simple as this:

Debt written down as an ADR

When a decision deliberately takes on debt, the ADR should say so out loud: what is postponed, what it costs, and when it has to be paid back. Space Travel wants to launch online booking before the season starts, but the full integration with the finance system would take too long. The team chooses to invoice manually in the first version:

The most important part of the example is not the wording, but that the repayment has a trigger: a concrete number that makes it clear when the interest has become too high. Without a trigger, "temporary" becomes "permanent", because there is always something more pressing.

When should you write an ADR?

Not every decision deserves a document. A good test is to ask: will a new colleague wonder in a year why it is like this? Typical candidates are the choice of database, framework or hosting model, boundaries between systems, the security model, and every decision that deliberately takes on debt.

Keep them short. A one-page ADR gets read; a ten-page one does not. Write it while the decision is being made, not afterwards, because the context is what you forget first. And also write down the options you rejected, with one line on why. That saves you the same discussion the next time someone suggests them.

The conversation with the business

Developers and the business often talk past each other about debt. "We need to refactor" sounds like a cost without a gain. It helps to translate into terms the business already uses:

• Principal: what does it cost to clean up? An estimate in days or sprints.
• Interest: what does the debt cost on an ongoing basis? Extra time per change, bugs in production, manual work, onboarding.
• Term: how long can we live with it, and what happens if we wait?

With those three numbers the decision becomes comparable to other investments. Sometimes the answer is to live with the debt, because the code rarely changes. Other times it is cheaper to pay now than to keep paying interest. Both answers are good, as long as they are deliberate and written down.

A good habit is to review the open debt ADRs at regular intervals, for example every quarter: have the triggers been reached, has the interest gone up, and is there new debt that should have been written down?