Architecture Decision Records: Governance and Enforcement
Architecture decision records governance covering the advice process versus central review boards, fitness functions that enforce decisions in CI and how to run ADR reviews and lifecycle without turning into paperwork.
13 min read
43 views
Key takeaways: architecture decision records governance 5
The governance and enforcement layer of the ADR practice, the part the template canon leaves open: how a decision stays binding and true over time, so records compound into trust instead of decaying into paperwork.
- Writing ADRs is solved, governing them is not The template layer of the ADR practice is commoditized. What most organizations actually struggle with is who decides, what makes a decision binding and why ADR archives go stale.
- Central review boards slow delivery without a matching safety gain Queue latency, distance from context and rubber-stamping are the recurring failure modes, consistent with the State of DevOps research on heavyweight change approval. Reserve a board for mandated or genuinely cross-cutting decisions.
- An advice process scales the way a board cannot Anyone can decide provided they seek advice from affected and expert people, with the ADR recording that advice and accountability staying with the decision-taker.
- A decision nothing enforces is a wish Fitness functions turn architectural decisions into automated CI checks, dependency-direction tests, policy-as-code and contract tests, so decisions stay true after the person who made them has moved on.
- Governance defaults depend on team size and regulatory context A single-team startup, a scale-up, a regulated organization and a distributed team each warrant a different default, treated as a starting point to reason from rather than a fixed rule.
Most engineering organizations have already solved how to write architecture decision records. Michael Nygard's 2011 essay set the template, adr.github.io collects the variants and AWS and Microsoft both publish prescriptive guidance on context, decision and consequences. What almost none of that canon covers is what happens after the record exists: who actually gets to decide, what makes a decision binding rather than a suggestion and why ADR directories fill up with documents nobody enforces or even rereads.
In short: writing ADRs is the solved part of the practice. Governance, meaning who decides and what makes the decision stick, is where most organizations quietly fail. A reasonable default for most product organizations is an architecture advice process with ADRs as the record of advice sought and given, plus fitness functions in CI as the enforcement layer, with a central review board reserved for the few decisions that genuinely need it. Hedge this against your own regulatory context - it is a starting point, not a rule.
The solved half and the unsolved half
Ask a team how to write an ADR and you get a fast, confident answer, because the template layer is commoditized. Ask who is allowed to make an architectural decision, what makes it binding on the rest of the codebase and why the ADR directory has forty entries from eighteen months ago nobody has revisited, and the confident answers stop.
A decision record with no governance model behind it becomes an archive of good intentions: it captures a decision that was made, not whether the right person made it with the right advice or whether the codebase still reflects it. That is the uncovered slice of the ADR conversation, and the more consequential one, since a well-written record enforced by nothing is not much better than no record at all. Governance is where the practice compounds into organizational memory engineers trust, or decays into paperwork written to justify a decision someone already made.
The review board problem
The default governance model many organizations reach for is a central architecture review board: a standing group of senior architects that any nontrivial decision has to pass through before it ships. It looks like rigor. In practice it tends to introduce three specific failure modes that show up almost every time.
Queue latency is the first failure mode. A board that meets weekly or biweekly turns every decision needing its sign-off into a wait, regardless of how well understood the decision already is. Distance from context comes second: the people voting are rarely the ones who will live with the consequences day to day, so the review becomes an exercise in explaining context rather than evaluating trade-offs the reviewers already understand. The third, and the one teams feel most acutely, is rubber-stamping. Once a board has approved enough decisions without real pushback, submitting to it becomes theater, a box to check rather than a genuine gate.
The State of DevOps research behind Accelerate found something consistent with this pattern: heavyweight external change-approval processes correlate with lower software delivery performance without measurably reducing the failure rate those processes exist to prevent. That does not mean central review is never warranted, only that it is not free, and organizations that add it as a default rather than a deliberate exception tend to pay for it in delivery speed without a matching gain in reliability.
There is a fair case for a board, narrower than most organizations that run one would admit. Regulated environments where a mandated control requires a documented, centralized sign-off and an audit trail are a legitimate use case, and so are the rare decisions that are truly cross-cutting and irreversible at the scale of the whole organization. The mistake is not having a board for those cases - it is routing every architectural decision through it because the mandated cases exist.
The architecture advice process
Andrew Harmel-Law at Thoughtworks has written the clearest alternative model: the architecture advice process. The rule is simple to state. Anyone in the organization may make an architectural decision, provided they seek advice from everyone meaningfully affected by it and from anyone with relevant expertise. The ADR becomes the record of that advice, who was consulted, what they said and why the decision-taker made the call they did. Accountability stays with the person who took the decision, not with a committee that approved it. A workable default for who counts as meaningfully affected: the teams whose systems the decision touches, whoever operates the result on-call and security or compliance when data or trust boundaries move.
This scales in a way a board structurally cannot, because decision-making capacity grows with the number of people empowered to decide, not with the bandwidth of a fixed group of reviewers. Expertise still flows in, since seeking advice from the right people is a requirement rather than optional courtesy, but without gating the decision on a reviewer's calendar. The team closest to the problem makes the call, at team speed, with the organization's collective knowledge factored in rather than approximated by a board meeting once a fortnight.
| Dimension | Review board | Advice process |
|---|---|---|
| Who decides | The board, by vote or consensus | The person or team closest to the decision |
| Latency profile | Bound to meeting cadence, often days to weeks | Bound to how fast advice can be gathered, often hours to days |
| Where accountability sits | Diffused across the board, hard to trace back | With the named decision-taker |
| How it scales with teams | Does not, one queue for the whole organization | Scales with headcount, each team decides at its own pace |
| Characteristic failure mode | Rubber-stamping once the queue grows long enough | Advice sought too narrowly, becoming a decision in name only |
The advice process has its own failure mode worth naming honestly: a decision-taker who treats "seek advice" as a formality, pinging one convenient colleague instead of the people actually affected. That is why the record matters as much here as anywhere else. An ADR that names who was consulted and what they said is auditable in a way a private decision never was, a real governance improvement over the informal status quo it usually replaces.
Enforcement: fitness functions in CI
A decision that nothing checks is a wish, not an architecture. Writing a decision down and getting agreement on it does not make it true of the codebase a month later, once the person who wrote the ADR has moved to the next feature and a new engineer who never read it starts importing across a boundary the record explicitly forbids.
"Building Evolutionary Architectures" by Ford, Parsons and Kua names the mechanism this article borrows: fitness functions, typically automated checks evaluated continuously or on change, that encode an architectural decision as a test the codebase either passes or fails. A decision to keep the domain layer free of framework dependencies becomes a dependency-direction rule enforced by an ArchUnit-style architecture test. A decision to standardize on one message broker becomes a dependency allowlist a CI job checks on every pull request. A decision about how infrastructure gets provisioned becomes a policy-as-code rule that fails the pipeline if violated, not a paragraph in a wiki someone is supposed to remember.
This changes what a mature ADR template should ask for. Alongside context, decision and consequences, an enforceable decision should record an "enforced by" field pointing at the specific check, an architecture test, a lint rule, a DevOps pipeline policy or a contract test. When a decision genuinely cannot be automated, the honest move is to say so and set a review date, not to leave it unenforced and hope.
| Decision type | Enforcement mechanism |
|---|---|
| Dependency direction between layers | Architecture test, ArchUnit-style |
| Tech stack or library boundary | Dependency allowlist checked in CI |
| Infrastructure or security policy | Policy-as-code rule in the deployment pipeline |
| API or service compatibility | Contract tests between consumer and provider |
| Naming or module structure | Lint rule or static analysis check |
Teams keep asking how a stack of team-local ADRs stays enforced once an organization has hundreds of them spread across dozens of repositories. Fitness functions are the honest answer: not a policy document that assumes everyone read and remembered it, but an automated check that fails the build when the decision it encodes stops being true.
When a check fails and the team believes the decision is now wrong, the right move is to supersede the ADR first, then retire or rewrite the checks that enforced the old decision in the same change, not delete them silently. A time-boxed waiver with an explicit expiry beats a silent override nobody revisits.
The review ritual: silent reading
Even inside an advice process, some decisions benefit from a real synchronous review, not to gate the decision but to genuinely test it against a room of people who will live with it. Amazon's meeting practice offers a useful ritual to borrow here, adapted rather than copied wholesale: reviewers read a written narrative silently at the start of the meeting instead of sitting through a slide presentation, then discuss it once everyone has actually absorbed the argument on the page.
Applied to an ADR review, the meeting opens with everyone reading the record itself, context, decision and consequences, in silence for the first several minutes, rather than watching the author talk over slides that summarize what the document already says better. Comments then anchor to specific passages in the text instead of floating impressions from half-attention. For distributed teams where a synchronous block is awkward across time zones, an async comment period on the document beforehand achieves something similar, provided it has a real deadline rather than running open-ended. Either way, timebox the discussion, and let the ADR's author close by explicitly recording any objections raised and the final call, which is exactly the accountability the advice process asks for.
Lifecycle governance
An ADR is not a permanent artifact and pretending otherwise is its own governance failure. Nygard's original template already includes a status field, proposed, accepted, deprecated or superseded, and the discipline that matters is using superseded honestly. When a decision changes, the right move is a new ADR that supersedes the old one and links back to it, not an edit that erases the reasoning that was true when it was made. History that stays visible is what makes an ADR archive trustworthy months or years later.
Decisions built on assumptions likely to age, a vendor's roadmap, current headcount, a regulatory requirement expected to change, benefit from an explicit review date rather than a hope that someone notices when the assumption breaks. An ADR belongs in the same repository as the code it governs, not a separate wiki that drifts out of sync with what shipped. Ownership of a decision follows ownership of the code.
Rolling it out without theater
The rollout that works starts with one team and a small number of decisions genuinely expensive to reverse, the same discipline a digital product management function applies when it sequences roadmap bets instead of committing to everything at once, not a mandate that every team retroactively documents everything it has ever decided. Record the decisions that would be painful to unwind, not every choice that happened to get made, and backfill sparingly, since a hundred-ADR archive written in a single sprint to satisfy an audit is rarely read afterward.
Organizations with an existing board migrate by inverting the default: sign-off stays only for a named short list of decision types, regulatory-mandated controls, irreversible cross-cutting choices, everything else moves to the advice process. Watch queue latency fall as that scope shrinks.
Three anti-patterns are worth naming so a rollout does not drift into them unnoticed. ADR-as-afterthought, where the record gets written after the decision has already shipped to retroactively justify it, defeats the point of seeking advice before deciding. A review board quietly renamed an "advice process" that still approves every decision in practice changes the label without changing the behavior it is meant to fix. And the hundred-ADR backfill, a burst of historical documentation nobody asked for and nobody will read, looks like governance maturity and functions as noise. A rollout that avoids these three earns trust in the practice faster than one that tries to look comprehensive from day one, and that trust determines whether the advice process, enforcement layer and review ritual above actually get used rather than performed. This governance layer complements, rather than replaces, the structural choices covered in our backend architecture guide, since a well-governed decision process is what keeps a chosen pattern from drifting once the team that picked it has moved on. Two cheap signals show whether governance is working: what share of accepted ADRs carry an enforced-by field, and how many have passed review without anyone looking.
Governance decision guide
None of the above is a universal rule - it is a set of defaults to reason from and depart from when your organization's context calls for it.
| Situation | Default governance |
|---|---|
| Single-team startup, early stage | Lightweight advice process, ADRs optional for the decisions that matter, fitness functions only where cheap to add |
| Scale-up adding multiple teams | Advice process as the default, ADR template with an enforced-by field, fitness functions for cross-team boundaries |
| Regulated organization with mandated controls | Advice process for most decisions, a narrow review board reserved for the specific controls that require centralized sign-off and an audit trail |
| Distributed or remote organization | Advice process with async comment periods replacing synchronous silent-reading reviews, explicit deadlines to keep momentum |
| Legacy estate with no existing records | Start recording new decisions going forward, backfill only the few historical decisions still actively causing confusion |
| Established org with an entrenched review board | Shrink board scope to a named decision list, advice process for the rest |
How Pharos Production runs architecture decisions
Inside client engagements we run architecture decisions with advice-process governance by default, with ADRs as the record of who was consulted and why, plus fitness functions wired into the pipeline wherever a decision can be automated rather than merely hoped for. Where a client's regulatory context calls for a narrower central review, we scope it to that specific control rather than routing every decision through it. If your organization is scaling past the point where informal architecture decisions stay legible, our custom software development team can help set up a governance model that fits its size and regulatory shape.
Sources: Michael Nygard's original ADR essay and the template canon at adr.github.io, AWS and Microsoft architecture decision guidance, Andrew Harmel-Law's architecture advice process writing for Thoughtworks, the State of DevOps research underlying Accelerate, "Building Evolutionary Architectures" by Neal Ford, Rebecca Parsons and Patrick Kua, plus Amazon's documented silent-reading meeting practice. Governance recommendations are presented as defaults, not fixed rules. Your best fit depends on team size, regulatory context and how distributed your organization is.
FAQ
Quick answers to common questions about custom software development, pricing, process and technology.
Type to filter questions and answers. Use Topic to narrow the list.
Showing all 5
No matches
Try a different keyword, change the topic or clear filters
-
An architecture decision record, or ADR, is a short written document that captures a single architectural decision, the context that led to it, the decision itself and its consequences, following the format Michael Nygard popularized in 2011. It exists so engineers who join later can understand why a system looks the way it does, not just what it looks like today.
What the format does not settle is who gets to make the decision it records, which is where governance starts.
-
ADRs are a record, not a governance model, so they do not automatically replace a review board. What replaces a board is a decision about who is allowed to decide, and many organizations get better results from an advice process, where anyone can decide after seeking advice from affected and expert people, with the ADR recording that advice.
A board still has a place for the narrow set of decisions that genuinely need centralized, audited sign-off.
-
A decision that nothing checks tends to drift the moment the person who made it moves on. The most reliable enforcement is a fitness function, an automated check in CI that fails the build when the codebase violates the decision, such as a dependency-direction test, a policy-as-code rule or a contract test.
Decisions that genuinely cannot be automated should get an explicit review date instead of being left to memory.
-
Write an ADR for decisions that are genuinely expensive to reverse, such as a core dependency, a data ownership boundary or a compliance-driven constraint. Under an advice process the call is the decision-taker's to make, and a cheap default settles most edge cases: if you sought advice from other people before deciding, the decision was significant enough to record.
That keeps the archive close to the decisions that actually mattered instead of every choice a team made along the way.
-
Following Michael Nygard's original template, an ADR should state the context that made the decision necessary, the decision itself and its consequences, both the benefits and the trade-offs accepted. The field worth adding on top of that template is "enforced by": which automated check or scheduled review keeps the decision true after the ADR is written.
A template without that field documents good intentions, not a decision anyone is accountable for keeping.
I work with startup founders who need a dedicated software development team but don’t want to gamble on hiring, random outsourcing, or opaque delivery.
Most founders face the same problem sooner or later.
Early technical and team decisions lock the product into tech debt, slow delivery, missed milestones and constant re-hiring. By the time this becomes visible, fixing it is already expensive.As a CTO and software architect, I help founders design, build and run dedicated development teams that work as a true extension of the startup. Not as a black-box vendor.
My focus is on complex products where mistakes are costly:
- Web3 and blockchain platforms
- FinTech and regulated products
- High-load startup systems
- MVP → scale transitions
We don’t do body-shopping.
We don’t sell generic outsourcing.Instead, we help founders:
- build the right team structure from day one
- keep technical ownership and transparency
- scale delivery without losing control
- avoid vendor lock-in and hidden risks
Teams are aligned with the product roadmap, business goals and long-term architecture. Not just short-term velocity.
