An architecture decision record, or ADR, is a short document capturing one significant design decision and the reasons behind it. Write one whenever you choose how to handle authentication, secrets, data storage, trust boundaries or third party risk. Months later it answers the question nobody remembers: why did we do it this way?
What an ADR is
The ADR community site defines an architecture decision as a justified design choice that addresses an architecturally significant requirement, and an ADR as the record that explains why the choice was made, with its trade offs and consequences. The collection of records in a project is its decision log. The site credits Michael Nygard's 2011 post, Documenting Architecture Decisions, with popularizing the idea, and notes that recording decisions goes back to the late 1990s.
Why security teams should care
Security decisions are where memory fails fastest. Examples:
- Why do we use this session mechanism and not that one?
- Why does this service hold its own credentials?
- Why did we accept the risk of a legacy library?
- Why is that network path open?
Without a record, the answers live in the head of someone who left. New engineers undo a deliberate choice because it looks odd, or keep a weak one because it looks intentional.
Which decisions deserve a record
Write one when the decision is hard to reverse, affects several teams, or shapes your risk. Good candidates:
- Authentication and authorization model
- How secrets are stored and rotated
- Encryption approach and key ownership
- Tenant isolation design
- Logging and retention choices
- Adopting or avoiding a significant third party component
- An accepted risk with a deadline for revisiting it
Skip the small stuff. A log full of trivia will not be read.
Keep it short
One page is plenty. Common sections, following the spirit of Nygard's original template (check the source for exact wording): a title, a status such as proposed, accepted or superseded, the context, the decision, and the consequences. Our companion post suggests an added security section.
Rules that help:
- One decision per record.
- Number them and never edit history. When you change course, write a new record and mark the old one superseded.
- Store them with the code, in the repository, so they go through review like everything else.
- Write them before or during the work, not after.
How they help in practice
Audits. Auditors and customers ask why controls are designed as they are. A dated record with reasoning is better evidence than a recollection. This is not a compliance requirement by itself, and no framework mandates ADRs, so treat it as good supporting documentation.
Incidents. When something fails, a record tells responders what was assumed. That speeds up the question of which assumption broke.
Onboarding. New staff read the log and learn the reasoning behind the system in an afternoon.
Revisiting decisions. Each record can name a trigger for review, such as a change in scale, a new regulation, or a deprecated dependency.
Getting started
Pick the last three security decisions your team made. Write them up in thirty minutes each. Put them in a docs folder, add a link in your contributing guide, and ask for a record in any pull request that changes a trust boundary.
Safeguard's policies, gates and compliance evidence automation can record the outcomes of decisions as enforced rules and collected evidence. The free scan is at gold.safeguard.sh/scan.
Quick check
Do ADRs replace design documents?
No. A design document explores a system. An ADR records a single decision and its reasons.
What if we later disagree with a record?
Write a new one that supersedes it and explain what changed. Do not rewrite the old record.
Sources
Last reviewed: 19 October 2026.
