Lesson 3 of 5
Decision records
10 min
Listen to this lesson
Two years after go-live, a new architect asks why core return agreements still run as classic ABAP, or why the portal sends orders asynchronously. If the answer lives only in the memory of people who have left, the team will either repeat the analysis or, worse, reverse a good decision without knowing why it was made. A decision record keeps the reasoning with the decision.
The architecture decision record
Michael Nygard proposed the architecture decision record (ADR) in 2011: a short document per decision, kept with the project, with a title, the context (the forces at play, described neutrally), the decision (stated in active voice), a status and the consequences, including the negative ones. Records are numbered sequentially and numbers are never reused. A record is proposed until agreed, then accepted; if a later decision changes it, the old record is marked superseded and points to its replacement, so the history stays visible. Nygard's rationale was that small, modular documents stay current where large specifications do not.
Additions for SAP transformations
The basic format works, and SAP programs benefit from a few extra sections. They make the record useful to testers, auditors and the next program.
| Section | Content | Why it matters |
|---|---|---|
| Options considered | Each option with a one-line summary of why it lost | Prevents re-litigating rejected options without new facts |
| Criteria and scores | The agreed criteria, weights and the scoring table | Shows the decision followed the framing |
| Quality and test consequences | What must be tested now, what regression it adds per release, what evidence is needed | Connects the decision to the test strategy |
| Assumptions and review date | Facts the decision depends on, and when to check them | Triggers revisiting when an assumption changes |
| Links | Cloud ALM requirements, related ADRs, SAP roadmap items or notes | Traceability from decision to delivery |
Useful extensions to the basic ADR format for SAP programs.
An example
Connecting records to delivery
A decision record earns its keep when the delivery tools point back to it. Link each accepted record from the requirements or features in SAP Cloud ALM that implement it, and reference it in the test strategy wherever it adds or removes test scope. ADR-007, for example, is why return agreements sit in the upgrade regression scope; when ADR-019 supersedes it, the test lead knows which regression tests can be retired once the rebuild is live. Without that link, regression suites keep tests for designs that no longer exist.
Where records live and who writes them
- Keep records where the team works and where they can be versioned: a repository folder, or a document area linked from SAP Cloud ALM.
- The proposing architect writes the record; the board reviews it; the decision owner accepts it.
- Write the record while deciding, not afterward. The context is freshest and the options are still real.
- Keep each record short: one decision, one or two pages. Link to analysis rather than pasting it.
- Never delete or rewrite an accepted record; supersede it with a new one.
- Week 1ADR-007 proposedOptions and scoring drafted by the architect
- Week 2ReviewedBoard and test lead review; test consequences added
- Week 3AcceptedDecision owner accepts; linked to Cloud ALM requirement
- After Wave 2ReviewedAssumption check: rebuild capacity confirmed
- Next releaseADR-019 supersedes"Rebuild return agreements on-stack" accepted; ADR-007 marked superseded
What would you do?
During hypercare, a developer proposes moving portal orders to synchronous calls "to show order numbers instantly". Nobody on the current team remembers why asynchronous messaging was chosen. What should happen?
- An ADR records title, context, decision, status and consequences; numbers are never reused.
- Records move from proposed to accepted, and are superseded, not deleted.
- For SAP programs add options, criteria, test consequences, assumptions with review dates and links.
- Write records while deciding; keep them short and where the team works.
Check your understanding · not graded
Lesson check
1. An architecture decision record captures:
2. What happens to an accepted ADR when a later decision changes it?
3. Which SAP-specific addition connects a decision to the test strategy?
4. When should a decision record be written?