Briefly: an architecture decision record is one page saying what you decided, what you considered, and why. On a Salesforce project it earns its keep more than on most, because so many platform decisions are permanent and the reasoning behind them is invisible in the org afterwards. Nothing in Setup tells you why person accounts are enabled.
The format
Five headings, no more:
# ADR-014: Contract renewals on a custom object
Date: 2026-03-11
Status: Accepted
Deciders: (names)
## Context
Renewals currently live as a second Opportunity with a record type.
Reporting cannot separate new business from renewals without a formula
on every report, and the sales pipeline number includes renewals.
## Options
1. Keep Opportunity with a record type
2. Custom object Renewal__c with a lookup to Contract
3. Contract object with a custom renewal process
## Decision
Option 2.
## Consequences
Renewal reporting is clean and the pipeline number is correct.
We lose Opportunity's forecasting, path and standard reports.
Anything reading Opportunity for revenue now needs both objects.The Consequences section is the one people leave out and the one that is worth reading later. It is where you record what you knowingly gave up, which is exactly what someone will later assume you overlooked.
What deserves one
Not everything. A record with forty ADRs for a two-year project is a record nobody reads. Write one when the decision is expensive to reverse, when two reasonable people disagreed, or when the choice looks wrong without the context.
On Salesforce specifically, these nearly always qualify:
- Standard object or custom object for a core business concept
- Master-detail or lookup on a relationship that carries sharing implications
- Enabling anything from the one-way list: person accounts, multi-currency, state and country picklists, a namespace
- Single org or multiple orgs
- Buying an AppExchange package rather than building
- Any integration pattern choice, because the next person will wonder why it is not the obvious one
Status, and why rejected ones stay
An ADR is never edited after acceptance. When the decision changes, write a new one that supersedes it, and mark the old one Superseded with a pointer. The old reasoning stays visible, which is the whole value: someone proposing a change needs to know it was considered and why it was not chosen then.
Keep the rejected options too. “We considered external objects and rejected them because we needed roll-ups” saves the next person a week of investigating external objects.
Where they live
In the repository, as markdown, in a docs/adr/ directory, numbered sequentially. Not in a wiki, not in a shared drive, not in a ticket. The repository is where someone is when the question occurs to them, and it is the only place that gets cloned when the project changes hands.
A pull request is also the right place to propose one. The discussion happens in review comments, the record captures the outcome, and the merge is the decision being accepted.
The Salesforce-specific value
On most platforms you can read the code and infer the design. On Salesforce a great deal of the design is configuration that looks identical whether it was carefully chosen or clicked by accident. A validation rule and a flow do not record why they exist rather than the other.
That is why the highest-value ADRs here are about things that are not visible in the metadata at all: why a field is maintained by an integration rather than a formula, why sharing is private on an object where public would be simpler, why one team’s records live in a different object from another’s.
Starting on an existing org
Write them retroactively for the decisions you can reconstruct, and mark them clearly as reconstructed. Start with the one-way doors, because those are the ones where someone will eventually propose undoing something that cannot be undone. Even an ADR that says “we do not know why this was enabled, and it cannot be disabled” is useful, and it is honest.
Frequently asked
Who writes it? Whoever proposed the decision. Not a separate documentation person, because the reasoning is the content and it does not survive being relayed.
How long should one be? A page. If it needs more, the decision is probably several decisions.
Do they replace design documents? No. A design document describes what is being built. An ADR records a choice between alternatives. Different jobs, and the ADR outlives the design document.
