---
title: "Architecture decisions, trade-offs, ADRs, and technical debt"
chapter: "06"
---

# Architecture decisions, trade-offs, ADRs, and technical debt

Architecting is deciding under uncertainty. Good records preserve the context, forces, alternatives, decision, consequences, evidence, ownership, and conditions for change.

## Core ideas and patterns

| Idea | What it solves | Cost, limit, or warning |
|---|---|---|
| **ADR** | Records one consequential decision and its status | A template does not replace reasoning |
| **Option matrix** | Compares alternatives against the same criteria | Weighted scores can hide weak evidence |
| **Reversibility** | Distinguishes one-way and two-way doors | Reversible still has migration and coordination cost |
| **Technical debt** | Makes a deliberate shortcut and its interest visible | Calling every weakness debt removes priority |
| **Prototype/spike** | Buys evidence before commitment | A prototype is not automatically production quality |
| **Real-options thinking** | Defers irreversible choice while preserving options | Delay has opportunity cost |
| **Decision trigger** | Defines when to revisit a choice | Calendar-only reviews miss operational signals |

## How to apply it

State the decision question before discussing products. List forces and rank them. Generate at least two credible alternatives including “do nothing.” Collect evidence proportional to irreversibility. Choose, record consequences, assign follow-up actions, and publish the ADR beside the system.

## Evidence, not opinion

Link ADRs to code, diagrams, controls, tests, dashboards, and migration plans. Track superseded decisions rather than rewriting history. Use drift checks for dependencies, network paths, data ownership, and forbidden coupling.

## Small example

Choose synchronous settlement now because the volume is low and correctness is dominant. Trigger a review when p99 exceeds 800 ms, settlement traffic exceeds 200 requests/s, or the provider availability objective falls below the product SLO.

## Feynman check

Explain the design to a new engineer without using the pattern names. State the
problem, the forces that conflict, the chosen boundary or mechanism, what can
fail, and the evidence that would prove the choice still works.