A new security engineer notices that the internal payments API skips mutual TLS, which policy requires everywhere. She asks why. Nobody knows. The Slack thread where it was negotiated is four years old and mentions a vendor constraint that no longer exists. The architect who approved it left in 2024. The exception, meanwhile, is still live, still load-bearing, and now has three more services built on top of it.
Every security team has a version of this story, because every security team runs on decisions, and almost none of them write the decisions down. An architecture decision record fixes that with the smallest possible tool: one short document per significant decision, stating the context, the choice, and the consequences, signed by the people who made it.
The format comes from Michael Nygard's 2011 essay, Documenting Architecture Decisions, and its defining property is that it is lightweight. An ADR is a page, not a binder. ThoughtWorks put lightweight ADRs in the "Adopt" ring of its Technology Radar years ago, and the practice is now common on platform teams. Security teams, who have more to gain from it than anyone, mostly still have not picked it up.
Why security decisions decay faster
All architectural knowledge erodes, but security decisions erode on a steeper curve, for three reasons.
Security decisions are disproportionately exceptions. The architecture that exists is mostly self-documenting; the deviations from it are not. "We require mTLS everywhere, except payments, because of the vendor" is exactly the kind of knowledge that lives in one person's head. Without a record, next year's reviewer sees only an inconsistency, and has to choose between two bad options: re-litigate it from scratch, or assume someone had a reason and wave it through. Both are expensive. One is dangerous.
The people rotate faster than the architecture. Median tenure in security roles is shorter than the lifespan of the systems being secured. The context walks out the door on a schedule; the decisions stay behind, unexplained.
The "why" gets asked years later, under pressure. Auditors, incident reviewers, and customers doing due diligence all ask the same question: why is it built this way? A team with decision records answers by retrieval. A team without them answers by archaeology, performed during the least convenient week of the year.
There is a fourth reason, and it is the one that should bother security leaders most: an undocumented risk acceptance is permanent policy made by whoever happened to be in the room. When "we accept this risk for now" is spoken but not recorded, there is no expiry, no owner, and no trigger to revisit it. The organization has changed its risk posture and has no memory of doing so.
The decisions worth recording
Not every choice needs a record. The bar is the same one used for security design reviews: would a competent future reviewer need to know why? In practice, security ADRs cluster in four groups:
Identity and access
- The authentication protocol and session model, and what they replaced
- How services authenticate to each other, and where that trust stops
- Privileged access paths: who can reach production, and through what
Data
- Classification boundaries: what counts as restricted here, and why
- Residency and jurisdiction calls, with the customer commitments behind them
- What is encrypted where, and the deliberate exceptions
Exceptions and acceptances
- Every policy waiver, with its compensating control and expiry date
- Every accepted risk, with the named owner who accepted it
- Every “temporary” bridge, because temporary is a decision too
Platform trust
- Third parties granted access to production or production data
- Build vs. buy calls for security-critical components
- Cloud primitives trusted instead of self-managed controls, and the reasoning
If a decision in one of these groups was made this quarter and no record exists, that is the backlog. Start there rather than backfilling history; retroactive ADRs written months later document what people wish they had thought, not what they thought.
The template
Nygard's original headings are context, decision, and consequences. For security work, three additions pay for themselves: explicit security implications, the risk being accepted and by whom, and a review date. Six headings, one page:
# ADR-041: Service-to-service auth stays on network policy until Q1
Status: Accepted
Date: 2026-07-16
Deciders: A. Reyes (Security), M. Chen (Platform), D. Okafor (Data owner)
## Context
What is true right now: the constraint, the deadline, the vendor
limitation, the incident that prompted this. Write it so a reader
in 2028 understands the room.
## Decision
One paragraph. Active voice. "We will..." not "It was felt that..."
## Security implications
What this weakens, what it strengthens, and what now depends on it.
## Alternatives considered
The two or three real options, each with the reason it lost.
## Risk accepted (and by whom)
The specific residual risk, and the named owner accepting it.
If nothing is accepted, say "None."
## Review date
The date this decision expires or gets re-examined. Every
acceptance gets one. No exceptions, including the exceptions.
The deciders line matters more than it looks. An ADR with named deciders is a decision; an ADR without them is a blog post. The same principle that governs sign-offs in a design review applies here: names create accountability, and accountability is what makes the record trustworthy years later.
The lifecycle
A record enters as proposed, becomes accepted when the deciders sign, and stays accepted until reality changes. When it does, nobody edits the old record. A new ADR is written, the old one is marked superseded with a link forward, and decisions that simply stop applying are marked deprecated. Then the loop begins again, because the new decision will eventually be challenged too.
The chain is the asset. ADR-041 superseded by ADR-063 superseded by ADR-078 is a readable history of how the organization's security posture actually evolved, including the dead ends. Deleting superseded records to keep the list tidy is like burning last year's audit evidence to keep the filing cabinet light.
Where the records should live
The graveyard for ADRs is a wiki space named "Architecture" that nobody opens during a review. Records rot there not because they are wrong but because they are elsewhere: the reviewer looking at a design has no reason to go searching for decisions that might be relevant, and so precedent goes unused and gets re-argued.
The fix is adjacency. Decision records belong with the design record they govern: next to the diagram, the threat model, and the sign-offs, in whatever system runs your secure-by-design workflow. When the next review of that system opens, the decisions are already in the room.
The anti-patterns
ADR theater
- Records written after the build, to justify what already shipped
- A twelve-section template so heavy nobody volunteers to write one
- No deciders named; status fields never updated after acceptance
- Records live in a wiki space disconnected from reviews
- Superseded decisions silently deleted or edited in place
A working practice
- The record is written while the decision is live, in the review
- One page, six headings, fifteen minutes to draft
- Named deciders, a review date on every acceptance
- Records attached to the design they govern, one click from the review
- Supersession chains preserved as the history of the posture
One more anti-pattern deserves its own sentence: the ADR that exists so a decision can be blamed on a document. If the record says "accepted" and no human name appears anywhere, the organization has invented a way to accept risk with nobody accepting it. That is worse than no record at all, because it looks like governance.
Starting on Monday
Pick the system heading into its next design review. Write ADRs for the three decisions about it that people already argue about, using the template above, with real names and real review dates. Attach them where the review happens. That is the entire adoption plan; the practice sells itself the first time a reviewer cites a record instead of reopening a settled argument.
We built this adjacency into our own product because we kept watching it fail in wikis: Alvor captures architecture decision records inside the security design review workflow, next to the diagram and threat model they governed, so the next reviewer reads the why in the same place they read the what.
Write the decision down while it is still a decision. Six months from now, it is folklore.