Architecture Decision Records: making enterprise decisions stick

The problem

In every long-running engagement, I watch the same thing happen: a crucial architectural decision is made in a meeting, the reasons live in somebody's memory, and six months later a new engineer asks "why does this work this way?" — and nobody can answer. Decisions get re-litigated, contradictory exceptions accumulate, and when an auditor or a new vendor asks why the platform is structured a certain way, the answer is "I think someone decided that a while ago."

That uncertainty is expensive. Every onboarding, every review, and every compliance conversation is slower because the reasoning behind decisions is not recorded anywhere.

The resolution

I started making decisions themselves a first-class artifact. Architecture Decision Records (ADRs) — short markdown files committed to the platform repo, one per significant decision, reviewed like code. The rule is simple: if a decision is expensive or hard to reverse, it gets an ADR before the code lands.

What a decision record looks like

The template is deliberately short — long enough to capture context, short enough that writing one never feels like paperwork:

# ADR-0042: Deny-effect guardrails over Audit for platform subscriptions

## Status
Accepted

## Context
New platform subscriptions kept accruing disallowed resource types between audits.
Audit-effect policy logged violations but did not stop them, so teams shipped anyway.

## Decision
Use the Deny effect for the platform guardrail initiative assigned at management
group scope. Waivers are handled through time-boxed Policy Exemptions.

## Consequences
Positive: non-compliant resources are blocked at creation, not reported.
Negative: a misconfigured policy can block legitimate work — mitigated by the
exemption workflow and a canary management group where policies land first.

The workflow

An ADR follows the same lifecycle as code:

• Drafted as a pull request alongside the change it justifies.
• Reviewed by the platform team — the discussion happens on the PR, not in a meeting.
• Approved and merged — the ADR becomes part of the repo history, and the reasoning survives every team change.
• Superseded — when a decision is revisited, the old ADR is marked superseded and a new one links to it, so the platform's evolution reads like a history book.

Enterprise impact

This is where the process pays for itself:

• Onboarding. New engineers read the ADR folder and understand why the platform is shaped the way it is, without a two-week shadowing period.
• Audits. When a compliance auditor asks why a control exists, you point at an ADR with context and consequences — not at a conversation nobody remembers.
• Faster reviews. Architecture reviews stop being debates about taste and become checks against recorded decisions: "did this change revisit ADR-0042?"
• Defensible rollbacks. When a decision turns out wrong, the consequences section tells you exactly what to expect and what to monitor.

Lessons learned

• Keep it boring. A template that is easy to fill in gets used; a fancy tool does not. Markdown in the repo beats a database in a wiki.
• Write the consequences honestly. The negative ones are what make an ADR credible to the next engineer and to an auditor.
• Attach ADRs to real change. An ADR with no code behind it is a slide. The decision and its implementation should land together.

The goal is not more process. It is that the platform's reasoning becomes a readable artifact — so good decisions stay good, and bad ones at least leave a trace.