Skip to content
People Leadership

Architecture Decision Records as a Decision-Rights Tool

Most teams adopt ADRs to remember why they chose a database. The sharper use is to settle, in writing, who gets to decide what, and to keep the manager off the approvals list.

People LeadershipEngineering Management Academy6 min read

A senior engineer on your team wants to move the notification service from polling to a message queue. Two other engineers disagree. The thread has been running for four days, you have been copied on all of it, and everyone is quietly waiting for you to settle it. Whatever you say next will teach the team how decisions get made here.

The usual advice is to document architecture decisions so that newcomers understand the system. That is true, and it is the smaller benefit. The larger one is that writing a decision down forces a question most teams never answer out loud. Whose decision is this?

What Nygard proposed

Michael Nygard's 2011 post on documenting architecture decisions is the origin of the architecture decision record, or ADR. His case was that large architecture documents are never maintained and rarely read, and that without the reasoning behind past decisions a new team member is left with two bad options. They can accept a decision blindly even though it may no longer apply, or reverse it blindly without understanding its consequences.

His fix was a short file in version control, one or two pages long, with a title, the context, the decision stated as "We will...", a status, and the consequences. He is specific that the context should describe the forces at play, "technological, political, social, and project local", in neutral language, and that the consequences should list everything that follows, good, bad and neutral.

Read that list of forces again. Political and social forces are management, and an ADR that records them honestly is recording who wanted what and why. That is the information a manager needs in order to be deliberate about decision rights.

The question an ADR forces

When a team writes its first ADR, somebody has to type the word "we" in "We will...". That moment exposes who the team believes "we" is. The senior engineer who wrote the draft? The three people in the design review? The manager who has to sign it off?

AWS's prescriptive guidance on the ADR process turns the answer into a process rule. Every team member can create an ADR, but each one has an owner who maintains and communicates it. The owner puts it in the Proposed state, the team reads it in a dedicated slot of ten to fifteen minutes and comments, and then accepts it, sends it back with named actions, or rejects it with a written reason. The guidance also records a benefit we think managers underrate. Understanding why the team decided "prevents other architects who weren't involved in the decision-making process to overrule that decision in the future".

That sentence is about you as much as about architects. If you were neither the owner nor a reviewer, you do not get to overrule the decision later because you feel differently in a one-to-one.

What the manager decides

We think the manager owns three things in this process, and none of them is the architecture.

Which decisions get a record. Nygard's bar is "architecturally significant", which is less a definition than an invitation to argue. The practical test we use in the Body of Knowledge is the one Jeff Bezos set out in Amazon's 2015 letter to shareholders. Some decisions are "consequential and irreversible or nearly irreversible", one-way doors, and most are "changeable, reversible", two-way doors. A schema change that three teams read from is a one-way door and gets a record. A library choice inside one service usually is not, and demanding a record for it is how the practice dies. Bezos warns that applying the heavyweight process to every decision produces "slowness, unthoughtful risk aversion, failure to experiment sufficiently", and that applies to an ADR process that grows too eager.

Who owns each one. The manager assigns the owner, or ratifies the team's choice, and makes it visible. This is the delegation move. Ownership of the queue decision goes to the senior engineer who raised it, with the two dissenters as named reviewers. The four-day thread now has a shape. A draft, a reading, a verdict, on a date.

Who is consulted. The social and political forces Nygard wants in the context section have owners outside the team. The platform team whose queue you would be using, the on-call engineer who will be paged when it backs up, the product manager whose feature depends on the date. The manager's job is to get those names onto the reviewers list before the review rather than into the retrospective afterwards.

What the manager refuses

Two refusals keep the tool honest.

Refuse to be the default approver. If every ADR needs your signature, the team will learn that decisions belong to you and will stop making them. Read the drafts, ask the question that is missing, and stay off the required approvals unless the decision is a one-way door you would not delegate at any level. There should be a short list of those, and the team should know what is on it.

Refuse to settle a decision in a side channel. If the queue decision gets made because the senior engineer caught you in the corridor, the ADR becomes paperwork recording a decision already taken elsewhere. The collection of ADR material maintained by Joel Parker Henderson on GitHub puts it bluntly. "Decisions are not valuable if they're just an after-the-fact forced paperwork requirement." Send the corridor conversation back to the draft.

Reading a record as a manager

You will read far more ADRs than you write. Read them for what they reveal about decision rights, and leave whether you agree with the architecture for the review.

A context section with no political or social forces in it usually means the author is avoiding a conversation. A consequences section with nothing negative in it means nobody with a reason to object was in the room. A record accepted the same day it was proposed, with the owner as the only reviewer, is a decision being laundered. None of those is a reason to overrule. Each is a reason to ask who else should have been consulted, and to put the answer in the record.

Over a year the decision log becomes something a manager cannot get any other way. It is an honest history of who decided what in your team, and whether the people who carried the consequences were ever asked.

Where this sits in the standard

Delegation, ownership and decision rights is competency PL-1 in the EMA Competency Framework, in the People Leadership domain. The PL-1 unit of the Body of Knowledge describes a decision-rights register that records who decides each recurring decision and at what level, and the TJ-1 unit covers evaluating the architectural decisions themselves.

Filed underdecision rightsarchitecturedelegationdocumentationengineering management
This sits under People Leadership in the Competency FrameworkThe Body of Knowledge chapter covers the full set of competencies the examinations assess in this domain.Read it →

Test your judgment, not your recall.

EMA-I is a scenario-based examination in the five domains of the framework. There is no course to buy and no attendance to prove. Sit a sample first, or read what the credential covers.

Keep reading