Use a one page ADR template with the usual fields, title, status, context, decision and consequences, plus a short security section covering data touched, trust boundaries, abuse cases, and how to reverse the decision. The extra questions take five minutes and force the security reasoning into the record.
The base
The ADR community describes an architecture decision record as capturing one decision with its rationale, trade offs and consequences, and points to Michael Nygard's 2011 post as the origin of the popular format. The template below follows that spirit. The security section is our own addition, not part of any standard.
The template
Copy this into a file such as docs/adr/0007-short-title.md. Use plain text.
0007: Short title of the decision
Status: proposed | accepted | superseded by 0012 Date: YYYY-MM-DD Deciders: names or roles
Context
What problem are we solving, and what forces apply?
Decision
What are we going to do? One or two paragraphs.
Options considered
Option A: summary, main trade off Option B: summary, main trade off
Consequences
What gets easier, harder or riskier?
Security notes
Data: what data does this touch, and how sensitive is it? Trust boundaries: what crosses one, and who validates it? Abuse cases: how might someone misuse this? Failure mode: what happens when it breaks, open or closed? Dependencies: what new components or services come in? Reversal: how do we undo this, and how long would it take? Review trigger: what would make us revisit this?
How to fill the security section
Data. Name the data classes. If it is personal data, say so, since that may trigger separate obligations to check with your privacy lead.
Trust boundaries. List every place input arrives from outside your control, including other internal services you do not own.
Abuse cases. Two or three sentences. Think about an unhappy customer, a curious insider and an automated scanner.
Failure mode. Decide on purpose. OWASP's secure design guidance says systems should fail in a secure state rather than expose vulnerabilities when they malfunction.
Dependencies. Name new libraries and services. Each one is something you now have to patch and trust.
Reversal. If it is irreversible, say so, and say why that is acceptable.
Review trigger. A date, a scale threshold, or an event such as a dependency reaching end of life.
An example entry
Decision: store uploaded documents in object storage with short lived signed links.
Security notes in brief: data is customer contracts, so sensitive. The boundary is the upload endpoint, which validates type and size. Abuse case: link sharing, mitigated by short expiry. Failure mode: if the signing service fails, downloads fail closed. Reversal: moving back to database storage would take weeks. Review trigger: any change to link lifetime.
Habits that keep it alive
- Require a record in pull requests that change a trust boundary.
- Keep the log in the repository.
- Number records and mark old ones superseded, never edit them.
- Review the log each quarter and check the review triggers.
If a record accepts a risk, link to wherever you track risks, and give it an owner and an end date.
Safeguard policies and compliance evidence automation can turn some recorded decisions into enforced rules. The free scan is at gold.safeguard.sh/scan.
Quick check
Is the security section needed for every ADR?
Include it on any record that touches data, access, or external services. For purely internal choices, one line saying none apply is fine.
Who approves an ADR?
Whoever owns the area. For changes to trust boundaries, add a security reviewer.
Sources
Last reviewed: 19 October 2026.
