Every healthy engineering org has a set of default technology choices — the language, the framework, the database, the patterns it reaches for first. Think of them as a paved path. Walking the paved path is the boring, correct default, and the whole point of having one is that you don't re-litigate it on every project. The interesting question isn't 'which stack should I pick?' — it's 'what do I owe everyone when I want to step off the path?' The answer is an ADR.
The paved path: your default needs no defense
Gold standards are the agreed-on defaults — chosen once, deliberately, for the whole organization rather than reinvented per project. When you use them as intended, you owe no justification and you write no decision record. That's the reward of the paved path: the choice has already been made and blessed, so reaching for it is free. A new project that uses the standard framework, the standard data store, and the standard patterns simply inherits all that prior thinking. Silence is the correct documentation for the default.
When you deviate, write an ADR
You only owe a record when you leave the path. In practice that means three kinds of change:
- a new library the standards don't list;
- a new external service or API the system will depend on;
- a new technical approach or pattern that differs from the standard one.
That record is an ADR: an Architecture Decision Record. It exists to capture why this project stepped off the paved path, so that six months from now, when someone wonders why one service runs an unusual database, the reasoning is written down rather than lost with whoever made the call. An ADR is the toll you pay for leaving the default, and it's a fair price: an hour of writing now against days of archaeology later.
The two ways to get this wrong. Some teams write an ADR for everything, so the log fills with records that restate the standards and nobody reads them closely any more. Others write one for nothing, and deviations surface months later, usually during an incident. The trigger is exactly one thing: leaving the paved path. Not the size of the service, not how important the choice feels.
How it works: what a good ADR contains
A good ADR is honest, not a sales pitch. It lists the alternatives considered, including staying on the gold standard, because an ADR that never mentions the default is hiding the most important comparison. For each option it states the trade-offs honestly rather than stacking the table so your preferred choice obviously wins; a comparison rigged to flatter your decision isn't a decision record, it's marketing. And it spells out the consequences: the future costs, the new maintenance burden, the things that get harder later.
Step through four choices below as they reach the same fork. Predict whether each one needs an ADR before you look. Then flip the ADR policy to replay the same week under a team that writes an ADR for every choice, and one that never writes any.
Here is roughly what that graph-database ADR looks like on the page. It fits on one screen, and each heading answers a question a future reader will ask:
- Context — what problem the standard doesn't solve well here. “Customers who bought this also bought” needs six self-joins in Postgres and takes about four seconds at our data size.
- Decision — what we'll do, and how far it reaches. Use a graph database for the Recommendations service only; orders and payments stay on Postgres.
- Alternatives — each with its honest trade-offs. Stay on Postgres with a cache (no new technology, but stale for hours). Precompute recommendations nightly (simple, but a day out of date). A graph database (fast, live, but a new system to run).
- Consequences — what this costs from now on. Someone has to operate, back up and upgrade a second kind of database, and on-call needs a runbook for it.
- Status — proposed, then accepted (or rejected) by the architect.
A few habits keep ADRs useful. Write one decision per record and keep it short. Number them and keep them with the code, where the next developer will look. And don't rewrite an accepted ADR when things change: write a new one that supersedes it, so the history of why survives.
Your gold standard for APIs is REST + JSON. A teammate building a new REST + JSON service drafts an ADR for it “just to be safe”. What's the best response?
Present, don't self-approve
There's a role boundary baked into this process. Juniors present ADRs; the architect approves them. You do the work of laying out the options and trade-offs honestly, then you bring that record to the person who owns the architecture. You don't get to wave your own deviation through. Self-approval defeats the purpose, because the whole value of the gate is a second set of eyes weighing your trade-offs against the wider system: the other services that will need to talk to your new database, the on-call rota that will have to support it, the next three teams who will copy whatever you did.
Presenting an ADR well is a skill in itself. Lead with the problem, not the technology you've fallen for. Make the strongest honest case for staying on the standard, and if it still loses, say why. An architect who can see you argued fairly against yourself can approve quickly; one who suspects the table was stacked has to redo your analysis.
In our stack — when Claude Code (the harness, on one of Anthropic's Claude models) is building a feature, its default is always the gold-standard choice — no decision record, no fuss. We instruct it to reach for a new library, service, or pattern only when the standard genuinely can't do the job, and when it does, to draft an ADR with the alternatives (gold standard included) and honest trade-offs. Claude Code presents that ADR; a human architect approves it. The agent proposes the deviation, it never self-approves it.
Where ADRs fit the bigger picture
Gold standards and ADRs are the engine of the technical track inside the greenfield workflow: the track starts from the standards and only branches into an ADR when a deviation is needed. The architecture document that follows then maps the system back to the standards and links every approved ADR, so a reader can see at a glance where, and why, this project differs. And the architect's approval is just one more of the review gates that govern the whole approach: a place where an artifact has to be good enough to pass, not merely exist. Keep your defaults boring, document your departures honestly, and let someone else hold the gate.
A developer wants a charting library that isn't in the gold standards. Their ADR carefully compares three charting libraries and picks one. What's missing?