Architecture Decision Record Template for Reviews
Table of Contents

48% of respondents to the 2025 State of Software Architecture survey said their teams use Architecture Decision Records. 52% said they don't, from a sample of 75 responses (State of Software Architecture survey 2025). A practice half the field runs without isn't a tooling problem. It's a question of what the file is for.
Most published templates answer one narrow question, what did we choose and why. That's necessary and it's not enough. A record listing context, options, and consequences still tells an auditor nothing about whether the control it describes is running in production today, or whether a coding agent implemented something adjacent to it last week.
This guide gives you the version I'd ship: a Markdown skeleton with the core fields, the security rows that make it survive a design review, a review-outcome block that stays separate from status, and a proof block with the observable evidence that the decision still holds. Paste the field table into docs/adr/template.md before you read the examples, so you can check each one against the structure instead of taking my word for it.
Why Teams Write an Architecture Decision Record
A record is one short file describing one architecturally significant choice made under competing forces, stored with the project it governs. It is not a design specification, not a meeting note, and not a comment buried in a ticket. Nygard's framing has aged well: without the forces, a future engineer has only two moves, accept the decision blindly or change it blindly.
The write triggers come from two sources that agree more than they disagree. Microsoft's guidance puts a record on any choice that changes system structure, moves a key quality attribute, or would be expensive to reverse. AWS adds security, availability, fault tolerance, dependencies, interfaces, and construction technique. In practice that means a new data store, a change in authentication, a queue that introduces eventual consistency, a boundary between tenancy models, or a control that only works if three services keep behaving.
The skip list matters just as much, because a repository full of noise stops being read.
- Cosmetic refactors. Renaming a module or splitting a file doesn't move a boundary and doesn't need a decision log entry.
- Dependency bumps that don't change behavior. A patch upgrade is a pull request. A major version that removes a security feature is an ADR.
- Notes with no owner. If nobody will ever be accountable for the choice, writing it down produces a document nobody maintains.
If the choice changes who can reach a data store or how a session is validated, it belongs in a security design review as well as an ADR, and the two should link to each other rather than describe the same decision twice.
A decision log earns trust by staying small and load-bearing. Ten records that map the real architecture beat two hundred that record formatting choices.
Fields in a Reusable Architecture Decision Record Template
The fastest way to standardize is to paste one skeleton into the repo and point the pull request template at it. This is the field set, in the order a writer fills it.
| Field | Required | What to record | Review expectation |
|---|---|---|---|
| Identifier and title | Yes | Sequential id plus a short decision name | One decision only |
| Status | Yes | Proposed, Accepted, Rejected, Deprecated, or Superseded | Binding only when Accepted |
| Date and deciders | Yes | Decision date and named people | Names, not a team alias alone |
| Context and problem | Yes | Forces, constraints, and the problem | Include the assumption that could expire |
| Decision drivers | Yes | Qualities that tipped the choice | Name security and compliance drivers when they apply |
| Options considered | Yes | Real alternatives and why each lost | Do not hide the rejected control |
| Decision | Yes | Committed wording such as We use | Reject should or consider |
| Consequences | Yes | Benefits, costs, and new work created | Record downside, not only the win |
| Links | Yes | Related ADRs, tickets, requirements, evidence | Bidirectional when superseding |
| Assets and trust boundaries | When security-relevant | Data, systems, and where trust changes | Required if a boundary moves |
| Threat-model reference | When security-relevant | Model id or link | Update the model in the same change |
| Control requirements | When security-relevant | Controls the decision depends on | Map each to a check the pipeline can run |
| Residual risk and owner | When security-relevant | What remains and who accepts it | Named owner, not a mailing list |
| Verification criteria | Yes for Accepted | Observable tests, policy checks, evidence locations | Accepted is not allowed if this is empty |
| Scope, participants, expiry | Yes | Service or repo, reviewers, review trigger | Sets the next reassessment |
The core rows track the field set Microsoft publishes for well-architected reviews, which treats each record as an immutable, append-only entry in a decision log rather than a document you edit later (Microsoft's guidance on architecture decision records). That single property is what lets the log serve as evidence two years on. An edited record proves nothing except that someone changed their mind.
File rules that keep the log trustworthy
Keep one decision per file so records can be superseded independently. Number files sequentially and never reuse a number, even for something you reject. Store the whole set in version control as plain Markdown next to the code, and treat the accepted body as frozen. Typo fixes and dead links are fine; rewrites are not.
The gate on Accepted
Status is a claim about intent, not a mood. Don't move a record to Accepted until the verification criteria row is filled in and a person has agreed to own the residual risk. If either is missing, the honest status is Proposed, even if the code shipped a month ago.
Practical rule: if you can't name the check that would fail when the decision stops being true, the record isn't ready to be Accepted.
When the security rows can stay empty
Leave the security rows blank only when the choice has no trust-boundary effect at all, such as a logging library swap, a build tool change, or a naming convention. The moment data crosses a process, network, or tenancy boundary, those rows become mandatory, and the threat-model row has to move in the same change as the decision rather than in a follow-up ticket nobody schedules.
Template Families and When Each Fits
Three template families cover most architecture decision records. Their field sets differ, but consistent use matters more than choosing a perfect format. The chart contrasts Nygard's concise structure with popular extended templates.

Michael Nygard's original article defines a short record with five fields: title, context, decision, status, and consequences (Nygard's original article on documenting architecture decisions). It focuses on choices affecting structure, non-functional characteristics, dependencies, interfaces, or construction techniques. The practical conventions remain sound: keep records with the project, number them sequentially, use lightweight markup, and preserve reversed decisions by marking the old record superseded instead of deleting it.
MADR extends the Markdown approach with a more structured template (the MADR project). Its current format brings options and drivers into the record and combines positive and negative effects in one Consequences section. Keep that balance. A record that lists only benefits reads like advocacy, not a decision that reviewers can assess.
ISO/IEC/IEEE 42010:2011 architecture-description guidance is a useful reference when someone questions whether a homegrown format is legitimate. It does not prescribe a file template, so it cannot determine your exact fields. Choose fields based on what reviewers must understand and verify, rather than treating a standard as a ready-made ADR form.
A Y-statement compresses a decision into one sentence: given a context and concern, choose an option over alternatives to achieve a quality, while accepting a downside. It works for a chronological index of small choices. It is too thin to carry review outcomes, residual risk, or evidence for an auditor or incident investigator.
| Family | Shape | Best use | Security gap |
|---|---|---|---|
| Nygard | Title, context, decision, status, consequences | Short structural choices in Git | No threat, residual-risk, or evidence fields |
| MADR | Numbered Markdown with options, drivers, and one Consequences section | Teams that want a fuller, consistent file | Review outcome and verification remain optional |
| Y-statement | One sentence covering context, concern, option, quality, and downside | Indexes and small decisions | Too thin for audit or design review |
| Security-extended record | MADR or Nygard with boundary, controls, residual risk, evidence, and expiry | Regulated or agent-assisted delivery | Adds fields that need owners and upkeep |
For regulated or agent-assisted delivery, standardize on Nygard or MADR and maintain one shared variant with security and evidence fields. The record should function as a security contract, not just a rationale and status: capture the review outcome, residual risk, and observable checks that show the decision still holds when code changes. Include checks that apply to agent-generated code as well. Six competing formats make records harder to scan and weaken confidence in the log; two formats in one repository are manageable when their purposes are clear.
How to Write the Core Decision Fields
Take a decision that's structural without being exotic: where the billing database lives. Call it ADR 014, Use regional active-passive for the billing database.
The context names the forces. One region meets the latency target. A regional loss stops invoicing entirely. Two engineers carry the pager, so anything requiring a second control plane during an incident is a liability rather than a capability. Drivers follow: a recovery point under 15 minutes, a recovery time under four hours, a monthly spend ceiling, and operational simplicity for a small team.
Then the options, including the one that lost. Active-active with conflict handling was rejected because invoice numbering would need reconciliation logic nobody wanted to own. A managed multi-region service was rejected on cost. Active-passive with automated failover won.
The committed line
Most drafts go soft at this point. "We should consider failover" is not a decision, it's a wish with a status field. Write it as a commitment other people can hold you to.
"We use active-passive failover for the billing database, with a 15-minute recovery point objective and automated promotion on region loss."
Same facts, and now a reviewer can disagree with something specific. Consequences come as a mixed list, not a victory lap: cross-region write complexity avoided, a failover runbook and rehearsed drill now required, and dual-region spend accepted. Status starts as Proposed, dated, with the two named deciders and the ticket link.
Why the context does double duty
The context paragraph is the only place to record the assumption that could expire, and expired assumptions are what make an Accepted record wrong without anyone noticing. "Two engineers on call" is a load-bearing fact. When the team grows to twelve and hires a dedicated SRE, the assumption behind the choice changed, and the record should be re-read rather than trusted.
Options need a loser
A record with one option isn't a decision, it's an announcement. Name the rejected control or the rejected architecture and say what it would have cost. Six months later that sentence is what stops the team from relitigating the same argument in a new meeting.
The fill order
- Write the context and the assumption that could expire.
- List the drivers, including security and compliance ones when they apply.
- Record the options, including the one that lost and why.
- Write the decision in "We use" form.
- List gains and costs together in one Consequences section.
- Set status last, after deciders are named.
A reviewer should be able to verify four things in about thirty seconds: there's one decision, the deciders are named, at least one option was rejected with a reason, and the consequences include a downside.
Security Drivers Threats and Review Outcomes
Now a record where the security content is the decision. ADR 021, Keep primary account numbers out of the application database.
The context names the asset, the trust boundary from browser to API to vault, and the compliance driver: shrinking card-data scope and satisfying a control the team already attests to under SOC 2. The threats belong in plain language rather than a full model. A primary account number gets written into an application log during debugging. A replica snapshot leaves the vault boundary. A generated migration copies the column back into a table because a model class still declares it.
Controls the decision depends on get listed one per line: tokenize at the edge before persistence, fail schema review if a column matching the card pattern appears, and alert on log patterns that match a card number. The threat-model row points at the model produced by your threat modeling process, not at a slide deck in someone's drive.

The review outcome is not the status
This is the block most templates are missing, and it's the one that makes the record usable in governance. Record who reviewed, on what date, and the result as Approved, Approved with conditions, Rejected, or Deferred. Then list the conditions that must be true before merge, and name the person who accepts residual risk.
Residual risk needs to be specific enough to be arguable. In this example, token values can still appear in support screenshots, accepted by the product security owner until redaction ships, with an expiry date attached. Specific, owned, and time-boxed. A line reading "some risk accepted" is noise.
The status and the review result stay separate. Leave the record Proposed while the result is Deferred or while conditions still block the merge. Set status to Accepted only once those conditions are done. Mixing the two is how teams end up with accepted records that describe an architecture they never built.
Practical rule: every condition in the review block should map to something a pipeline or a person can check. If a condition can't fail, it isn't a condition.
Agent lineage when an agent implements the control
If a coding agent or assistant will build part of this control, add lineage before it runs, because the behavior of an AI-assisted system can shift without a conventional release: a model swap, a prompt edit, a retrieval allow-list change, or a safety-filter update all alter what ships (RSAC field notes on AI infrastructure governance). Fill it in this order.
- Model or agent name and version.
- Tool permissions and retrieval sources it may touch.
- The human approver who signs off before merge.
- Prohibited actions, such as editing migrations or disabling the schema rule.
- The reassessment trigger if the prompt, allow-list, safety filter, or tool list changes.
That last field catches the quiet case: a record still marked Accepted, still architecturally accurate, and no longer describing how the code is produced.
Evidence That the Decision Still Holds
A decision record can be Accepted and still describe a system that no longer exists. Popular templates capture context, options, rationale, consequences, and status, as the Architecture Decision Record community index shows. To make the record useful after implementation, add a security contract: observable checks, review outcomes, residual risk, and evidence that the decision remains true in production.
The proof block should name implementation evidence, such as a repository path, pull request, infrastructure module, or test. Each acceptance criterion must be observable and capable of failing. For example, a build can fail if a column matches the card pattern, a policy check can block a merge when the threat-model link is stale, and a model update can be required in the same change as a design change. A statement that someone plans to wire up a check is not evidence.
Name the verification owner and cadence, too. For stable infrastructure, a quarterly review may be sufficient; a trust-boundary change should trigger a review regardless of the calendar. Record drift or exceptions when implementation diverges from the decision. Set an expiry for each exception, document its residual risk, and create a successor record if the original decision no longer holds.

An AI-generated summary saying a design “looks fine” does not establish conformance. Require the same evidence from agent-produced changes as from human-written code: checks tied to the approved decision, plus review outcomes that show whether the controls passed. The record should let an auditor or incident investigator answer a concrete question: what observable fact shows this decision is still true in production?
Two fitness checks, one per record
For ADR 021, use a schema rule in the migration pipeline. Fail the build if a column's name or type matches the card pattern, and run the rule on every pull request that touches models. For ADR 014, store the failover drill result alongside the record, including its date and measured recovery point and recovery time. Both checks turn a claim into evidence another reviewer can inspect.
That is the distinction between a decision log and an executable security contract. The post-implementation verification work connects approved decisions to checks after implementation. If a record cannot identify a check that can fail, its rationale may still be useful, but it does not demonstrate that the architecture continues to meet the decision.
Status Links and Superseded Records
Status is an operation, not a label. The lookup below is what a writer should consult before touching any field.
| Status | Meaning | Next action |
|---|---|---|
| Proposed | Under review and not binding | Collect deciders and conditions |
| Accepted | The team will implement this choice | Attach evidence and a review trigger |
| Rejected | This option lost; rationale stays | Link from the accepted record |
| Deprecated | No new use; existing systems may remain | Name the replacement or removal date |
| Superseded | A newer ADR replaced this one | Keep the body and link both ways |

When an accepted choice changes, the order of operations matters more than the wording.
- Do not overwrite the accepted body.
- Mark the old record Superseded by the new number.
- Create the next sequential record with the new decision.
- Link both directions, old to new and new to old.
- Explain the trigger in the successor's context, such as a drill that missed the recovery point or a new regulatory constraint.
AWS's prescriptive guidance on architectural decision records is blunt about the surrounding practice: keep records in a central, version-controlled location, require consistent anatomy across teams, name owners, and retain superseded history rather than archiving it away (AWS prescriptive guidance on ADR best practices). That last point is the one teams get wrong when they tidy up. Deleted history looks clean and destroys the audit trail.
Cross-reference types worth naming
- depends-on means this decision only holds if another one does.
- supersedes points forward to the record that replaced this one.
- related threat model ties the design claim to the model that justifies it.
- policy or control id maps the decision to the control it satisfies.
- implemented by links the ticket or pull request that built it.
One chain makes the pattern concrete. ADR 014 is superseded by ADR 032 after a drill misses the recovery point. ADR 014 keeps its body, gains the supersession line and a backlink, and ADR 032's context explains what the drill measured and which assumption broke, most likely the cost ceiling that made the managed service unattractive a year earlier.
The reconstruction test is simple. A reviewer opening the log cold should see why the first choice won, why it was replaced, and which assumption expired. If any of those three requires asking a person, the links are incomplete.
Store the Record and Keep It Current
Set the repository up once so the next significant change produces a numbered record without a debate about where it goes.
- Create
docs/adrand paste the Markdown skeleton from the field table, security rows and verification block included. - Number the first file 0001, and keep accepted bodies unchanged. Replacements follow the supersession steps.
- Add a line to the pull request template: does this change move a trust boundary, a data store, an authentication method, or an external dependency, and if so which ADR covers it.
- Treat a missing review outcome, residual-risk owner, or verification criterion as a merge block for security-relevant records.
- Review assumptions older than six months, and sooner whenever a model, prompt, retrieval source, or tool permission changes.
The Git file stays the source of truth even when tickets are messy and the design doc is half finished. A record that lives only in a planning tool dies with the planning tool.
DevArmor can hold that same decision as an audit-ready security-architecture artifact for SOC 2 and ISO 27001, with each review traceable to the approved record while code is generated, which is roughly where a static file stops being enough.
The shipping rule is binary. The next boundary-changing pull request cites a numbered record, or it doesn't ship.
DevArmor turns the record you just wrote into something the delivery pipeline can enforce: a living security context that stays current as the design evolves, pushes design controls and guardrails into the tools your engineers and coding agents already use, and keeps every review traceable to an approved decision or threat model. If your team writes ADRs that nobody verifies, start with a template your pipeline can read and visit DevArmor to see how the review, the evidence, and the code change stay connected.
Table of Contents
Subscribe

