What Is an Architecture Decision Record?
An Architecture Decision Record (ADR) is a short document that captures a single architectural decision, the context that led to it, the options considered, the decision made, and its consequences. Originally proposed by Michael Nygard, ADRs are stored in version control alongside the codebase — where they can retain commit history and, when the repository workflow records it, an associated pull-request review trail.
For PCI DSS purposes, three properties can make ADRs useful supporting evidence:
Where ADRs Can Support PCI DSS Assessment Evidence
An ADR does not satisfy a requirement on its own. It can contribute context and traceability when it is reconciled with the policies, configurations, tickets, test results, inventories and operational records the applicable testing procedure asks the assessor to examine. These mappings are practical examples rather than a substitute for the standard.
| Sub-req | Requirement text (summary) | How an ADR can contribute | Evidence still needed |
|---|---|---|---|
| 6.3.1 | Security vulnerabilities are identified, risk-ranked and managed | Records why a library, platform or component change was selected in response to a vulnerability | The vulnerability-management process, recognized sources, risk rankings and evidence that the process operates |
| 6.5.1 | Production changes follow established change-control procedures | Captures the reason, description, security impact, approval, test references and recovery considerations for a change | The approved procedure plus sampled change records, test results, deployment evidence and failure or rollback handling |
| 6.5.2 | Applicable PCI DSS requirements are confirmed after a significant change | Links the significant change to affected requirements, documentation updates and validation activities | Evidence that applicable controls were confirmed in place on the changed systems and networks |
| 2.2.1 | Configuration standards are developed, implemented and maintained | Documents why a hardening baseline or vendor recommendation was selected and how deviations are governed | The standards themselves plus configuration and interview evidence showing they are current and applied |
| 12.3.2 | A TRA is performed for each requirement met with the customised approach | Points to the control objective, controls matrix, TRA owner and senior-management approval | All Appendix D information, the controls matrix, annual TRA, approval, control testing and ongoing-effectiveness evidence |
| 12.3.3 | Cipher suites and protocols are inventoried and reviewed at least annually | Records a cryptographic decision, migration plan or response to an industry change | The current inventory, annual review, trend monitoring and documented response plan |
| 1.2.3 / 1.2.4 | Network and account-data-flow diagrams are accurate and maintained | Links an architecture change to the diagram versions that should be updated | Current diagrams reconciled with the implemented network and account-data flows |
| 8.6.2 | Interactive application and system account passwords are not hard coded | Records the chosen credential-management pattern and affected systems | Procedures plus examination of scripts, configuration files and custom source code for applicable accounts |
Mappings are illustrative. Applicability and assessment evidence must be determined from the current PCI DSS standard, validation method and assessor testing.
How to Test Whether ADR Evidence Is Reliable
When an entity presents ADRs as supporting evidence, the review should test five dimensions and reconcile the records with the implemented environment:
Write ADRs That Reduce Assessment Follow-Up
This template helps an ADR contribute useful context and traceability. It does not replace change tickets, configurations, test results, logs, inventories or the formal documentation required for a customised approach.
ADR template for PCI DSS supporting evidence:
# ADR-[number]: [Decision title] ## Status [Proposed | Accepted | Superseded by ADR-xxx | Deprecated] ## Date [ISO 8601 date — reconcile with the decision and implementation timeline] ## Context [What is the problem being solved? What is the current state of the CDE component affected? Include the PCI DSS requirement that this decision affects, if applicable.] ## Decision [What was decided? Be specific — include service names, configuration values, and the authorising individual or group.] ## Alternatives considered [What else was evaluated? For each alternative, include why it was rejected — particularly any security reason for rejection.] ## Security implications [What are the security consequences of this decision? Does it introduce new attack surface? Does it remove a compensating control? What is the residual risk?] ## Potential PCI DSS evidence links [List the requirements this record may support. Confirm applicability against the current standard and assessment scope.] ## Implementation reference [Change ticket: JIRA-1234] [Implementation PR: github.com/org/repo/pull/567] [Deployment or audit event reference: event-abc-123] ## Approved by [Name, role — where approval is required by the change procedure]
Use ADRs Carefully with the Customised Approach
PCI DSS v4.0 introduced the Customised Approach for entities that meet a requirement's Customised Approach Objective without strictly following the Defined Approach requirement. PCI DSS 12.3.2 and Appendix D require extensive documentation, including a controls matrix, targeted risk analysis, senior-management approval, testing and ongoing-effectiveness evidence. An ADR can link these records, but it is not their automatic replacement:
- Link to the Customised Approach Objective and controls matrix rather than describing the ADR as replacing a PCI DSS requirement.
- Describe the customised control and implementation, then link to the evidence used to test it.
- Reference the documented targeted risk analysis required by 12.3.2, including its annual review and senior-management approval.
- Use repository history for traceability, while retaining the required documentation, testing and monitoring evidence.
Evidence gap to avoid: An ADR that records the design decision but omits the controls matrix, targeted risk analysis, senior-management approval, testing method or ongoing-effectiveness evidence is incomplete for the Customised Approach. Confirm the documentation set with the assessor early.
Payment Architecture & Evidence Workspace
Turn this guidance into a structured decision
Open the relevant workspace tool to apply the article to your payment environment. Eligible membership access may be required; the tool page shows access before you begin.