An architecture decision record, or ADR, is a short document that, in the words of the ADR community site, "captures a single AD and its rationale". Most teams keep them as Markdown files beside the code and accept them in a pull request. That works well for the engineering part of a decision. It gets harder when the same ADR also commits money, a supplier, a date or a risk that someone outside the team has to agree to.
I founded Traceway, so read this as a vendor's view. The descriptions of ADR practice below come from published guidance, which I link, and not from a survey of how teams actually work.
What the established guidance says
AWS's ADR process guide gives each record a state: Proposed, Accepted, Rejected or Superseded. The project team reviews a proposed record, and "when the team accepts an ADR, it becomes immutable". A changed decision is a new ADR that supersedes the old one.
Microsoft's Well-Architected guidance describes the same discipline as "an append-only log" and asks each record to hold the problem, the options considered, the outcome with its trade-offs, and a confidence level. Both guides are about getting the team to write down why, and to stop rewriting history.
Both describe review and acceptance by the team doing the work. Neither sets out who outside that team has to approve a cost, a contract or an accepted risk. That is left to your organisation, and it is where an ADR on its own can run out.
When the team's acceptance is not the whole decision
Take a fictional ADR: move session storage from a self-hosted cluster to a managed cache from a new supplier. The engineers agree and the pull request merges. The ADR is accepted.
The same choice also means a three-year commitment, customer session data held by a new processor, and a migration that moves a release date by five weeks. Finance owns the commitment. Security and privacy own the risk. A product leader owns the date. None of them reviews pull requests, and the ADR does not show whether any of them agreed.
| Question | ADR in a repository | Business decision record in Traceway |
|---|---|---|
| Who accepts it | The project team, in the review the guidance describes. | Named people in named roles. Approval is a separate human act on the record. |
| Who can take part | People comfortable with Markdown, commits and pull requests. | Anyone who can use a document editor. Trace AI can help draft and refine; people can also write directly. |
| What it is tied to | The code change it explains. | The goal it serves and the work that follows, through Strategy Alignment. |
| When it changes | A new ADR supersedes the accepted one. | The owners can see which commitments to revisit. |
The table describes published approaches, checked on the date above. It is not a claim that a repository cannot be configured to do more, and it is not a feature score.
Keep the ADR, and record the business decision beside it
I would not move the ADR. It belongs with the code, and engineers should keep reviewing it there. What I would add is one business record for the commitment: what was approved, by whom, with which alternatives set aside, and a reference to the ADR that carries the technical reasoning.
In Traceway that record holds the rationale, the alternatives, the roles and the approval. Our Jira connection can create the work that follows and then becomes read-only. A later change to the decision does not update those tickets automatically; the delivery owner still has to. Azure DevOps, Linear and GitHub Issues are on our roadmap and are not available today. If your delivery work lives there, that handoff is manual for now.
A test you can run in half an hour
Pick one accepted ADR from the last year that cost money or moved a date. Ask three questions of whatever you use today.
- Who, outside engineering, agreed to the cost or the risk, and where does it say so?
- Which alternative did they turn down, and why?
- If the supplier's price rose next quarter, who would be told that this decision needs another look?
If the answers are in the ADR and its pull request, you may not need anything else. If they are in someone's memory or a chat thread, that is the gap a business decision record fills. Our guide to decisions that belong to more than engineering goes further into where the line sits, and the decision behind an architecture change covers the enterprise-architecture tools.
To try it on your own ADR, bring one to a Traceway demo and ask us to show the approval, the alternatives and the link to delivery in the scope you are considering.