Architecture decisions are business decisions wearing technical clothing. When an executive asks "why are we moving to event-driven architecture?", a 30-page design document is not an answer. Neither is "because it scales."

The architecture decision record (ADR) is a small, durable artifact that captures a choice and its consequences. Most ADRs are written for engineers. The version executives need is shorter, more explicit about cost, and honest about uncertainty.

The one-page structure

Use six sections, each a few sentences:

  1. Decision. What we are choosing, in plain language.
  2. Context. The business constraint forcing a choice now.
  3. Options. Two or three credible alternatives, including "do nothing."
  4. Trade-offs. What each option buys and what it costs.
  5. Consequences. Reversibility, operating cost, hiring impact, and timeline.
  6. Review date. When we will revisit if assumptions change.

That is it. If a decision cannot be explained in this structure, the team does not yet understand it well enough to commit.

Lead with reversibility

Executives manage risk portfolios. The most useful question is not "is this the best architecture?" but "how expensive is it to undo?" A two-way-door decision can be delegated and made quickly. A one-way-door decision deserves review and a written record. Label every ADR accordingly.

Cheap-to-reverse decisions need speed. Expensive-to-reverse decisions need evidence. Confusing the two is how organizations become either reckless or paralyzed.

Quantify where it matters

You do not need false precision, but you should estimate the operating delta. Will this add $8k per month in infrastructure? Require two additional specialists? Delay the roadmap by six weeks? Executives are fluent in these units. Use them.

Review in public

Discuss the ADR in a forum where product, finance, and engineering hear the same reasoning. This does not turn architecture into a committee. It creates a shared record of intent and gives future teams the context they will need when the original authors have moved on.

The best ADRs are not monuments. They are working tools: short, dated, and easy to revise when reality disagrees.