Insights · Architecture Governance

Making ADRs work: governance engineers actually follow

ADRsTOGAF

Key takeaway

ADRs work when they are the path of least resistance: short, numbered, versioned, and written by the people doing the work.

What governance actually costs when it’s absent

The failure mode of ungoverned architecture isn’t chaos; it’s relitigation. The same integration argument, had by different people, every six months, with no memory of the last conclusion. Meanwhile the platform accretes: two message queues, three logging formats, four ways to deploy, and nobody who can say why. On a multi year programme the cost compounds, because staff rotate, vendors change, and every departure takes institutional memory with it.

Architecture Decision Records are the cheapest countermeasure we know: a page per significant decision, in version control, that answers what did we decide, when, and why, including what we rejected. The format is Michael Nygard’s, proposed in 2011 as one short document per architecturally significant decision — a record written as “a conversation with a future developer” (Nygard, “Documenting Architecture Decisions”), since maintained and extended by a community around adr.github.io.

Anatomy of an ADR that gets read

  • One decision, one record. If a record covers four decisions, none of them are governable.
  • Numbered and dated. ADR-007 means something when it’s cited in a design review; “the Kafka one” doesn’t.
  • Context before conclusion. The constraints that made the decision necessary are what make it reusable, and what let a successor supersede it honestly when constraints change.
  • Options considered, with the rejection reasons. This is the single highest-value section and the first one people skip. “We chose X” is trivia; “we rejected Y because Z” is institutional knowledge.
  • Consequences stated plainly, including the costs accepted, not just the benefits claimed.
  • Status that can change. Proposed, accepted, superseded, never “final”. Decisions that can’t be superseded get ignored instead.

The practice: 15 ADRs, 30+ selections

On the UNDP-supported E-Tax modernization for Rwanda Revenue Authority, 15 ADRs governed more than 30 technology selections across the programme: API management, service mesh, observability, CI/CD, platform engineering, security. They weren’t decoration; they were the working instrument for several hard calls:

  • Gateway security and defense-in-depth: the programme’s first ADR, because edge policy shapes everything behind it.
  • Default-strict mTLS for east-west traffic: a default-on trust posture, decided before the first service existed.
  • Secrets management, including the interim: even the transitional choice (SoftpHSM for vault auto-unseal) got a record, because interim arrangements without records become permanent ones.
  • Kafka consumer autoscaling, topic retention, connector strategy: the event backbone governed decision by decision, not as one monolithic “we use Kafka”.
  • Traffic splitting for the monolith coexistence: the migration’s control surface, written down before traffic moved.

Two principles did the heavy lifting: open-source-first evaluation and least cost of tax collection. Codified up front, they turned vendor conversations from persuasion exercises into constraint checks, and the ADRs record where the expensive option lost.

Four ways ADR practice dies

  1. The essay standard. If records take a week to write, only architects write them, and they arrive after the decision. One focused page, written in the meeting’s aftermath, beats a masterpiece a month later. ThoughtWorks has listed lightweight ADRs as Adopt on its Technology Radar since 2017 — “For most projects, we see no reason why you wouldn’t want to use this technique” — a verdict on the lightweight practice, not the literary one (ThoughtWorks Technology Radar, “Lightweight Architecture Decision Records”).
  2. Living in a wiki. ADRs live in version control, beside the code they govern, reviewed through the same pull requests — Google Cloud’s Architecture Center puts them “close to your application code, ideally in the same version control system” (Google Cloud, “Architecture decision records overview”). A wiki page competes with nothing and links to less.
  3. No supersession path. When a decision must change and the process makes that shameful, teams simply stop citing the record. Microsoft’s Well-Architected Framework states the alternative as structure: “The ADR serves as an append-only log. Don’t go back and edit accepted records. If a decision changes, write a new record that supersedes the original and link the two together” (Microsoft, “Maintain an architecture decision record (ADR)”). Supersede openly, link the old record to the new one.
  4. Governance as gatekeeping. If engineers experience ADRs as permission slips for the architecture police, they’ll route around them, and rightly so. The test: engineers should be the primary readers, citing records in design docs and pull requests unprompted.
Rule of thumb

If your ADR catalogue answers “why is it built this way?” in under a minute for any major component, governance is working. If anyone answers “let me ask Dave”, it isn’t.

Starting (or restarting) yours

Backfill is fine: pick the five most load-bearing decisions your platform already embodies, write them down with their real history (status: accepted, retrospectively), and govern forward from there — the field-by-field page format is its own guide, How to write an ADR. And if you want the governance stood up properly (forum design, triage of the back-catalogue, adoption in delivery), that’s a conversation: start one.

Discuss your governance setup

Sources