Before a significant rewrite or architectural change, write down the decisions that shaped the current system: the problem they solved, the options that were rejected, the choice that was made, and what that choice costs today. An architecture decision record (ADR) is the lightweight format most teams use for this. Without one, a rewrite tends to re-open decisions that nobody remembers making, and the reasons behind them are lost along with the people who made them.
What an ADR captures, and what it does not
An ADR is a short document that records one consequential decision. It is not a design specification, a code walkthrough, or a complete map of the system. Its job is to explain why the system is shaped the way it is, so that future maintainers can judge whether the original reasons still hold.
- Record structural choices, not coding details. ADRs suit decisions that affect system structure, quality attributes such as security or availability, dependencies, interfaces, and major construction techniques, especially where real alternatives existed. Google Cloud’s ADR guidance and AWS Prescriptive Guidance both draw the line at decisions with lasting consequences.
- A useful record contains context and consequences. The problem and its constraints, the relevant requirements, the alternatives, the chosen option with its rationale, and the implications for the system and the project. A record that lists only the outcome (“we use Kafka”) is close to useless once the team changes.
- Records must be easy to find. A Markdown file stored with the code in version control gives you a searchable, time-stamped history. A wiki or shared document can be better when readers outside engineering, such as product or compliance staff, need access.
- Accepted decisions are kept, not rewritten. When a decision changes, you add a new record that supersedes the old one and links to it. The earlier reasoning stays visible.
- ADRs complement broader architecture documentation. A decision log explains why choices were made. It does not show components, relationships, or deployment. Use architecture views or design documents for that.
When a decision deserves a record
Write an ADR when a consequential decision has no existing documented basis, when a solution is otherwise undocumented, or when several engineering options must be weighed and one selected. A practical test is whether a future contributor could reasonably ask why this choice was made, or what trade-off it accepted. If the answer is yes, write the record. If the choice is easily reversed and affects only one module, a code comment or pull request description is usually enough.
Anatomy of a record
Google Cloud lists context, requirements, options, decision, and reasons among useful sections. AWS adds consequences and its guidance on scope. Templates vary, and a record can run to one page or several, but the sections below cover what a future reader needs.
#1 Best Overall
| Section | What to write | Test question for the author |
|---|---|---|
| Title and status | A short, specific title, a number, the date, and a status such as proposed, accepted, or superseded | Could someone find this record by searching for the problem it solves? |
| Context and constraints | The problem, the current state, and the limits that shape any answer, such as budget, team skills, regulation, or existing contracts | Would a reader understand the problem without asking anyone? |
| Requirements | The functional and quality needs the choice must meet, such as latency targets, availability, or security obligations | Are the requirements measurable, or only aspirational? |
| Options considered | Each realistic option, including the status quo where it applies, with its main strengths and weaknesses | Is the status quo included, so that doing nothing is an explicit choice? |
| Decision | The option chosen, stated in one or two sentences | Could a reader tell exactly what was agreed? |
| Rationale | Why this option beat the others against the stated requirements | Does the reasoning point back to the requirements rather than to preference? |
| Consequences | Trade-offs accepted, follow-up work, operational impact, and assumptions to revisit | What would a future maintainer need to check if this assumption fails? |
Writing a record, step by step
- Name the architectural question. Choose one that affects structure, quality attributes, dependencies, interfaces, or a major construction technique.
- State the problem, the constraints, and the requirements that matter to the choice. Write them before you look at options, so the requirements are not bent to fit a favourite tool.
- List realistic options. Include the status quo where relevant. Two or three options is typical; a long list usually means the question was framed too broadly.
- Record the chosen option and the reason it won. Keep the reasoning short enough that a new engineer can read it in a few minutes.
- Write the consequences: the trade-offs, the follow-up tasks, and the assumptions that should be revisited.
- Save the record near the code or in a documented team repository, and review it before marking it accepted. Review should check that the options are real and that the reasoning follows from the requirements.
- If the decision changes later, create a new record that supersedes and links to the prior one.
Illustrative example
The following record is hypothetical and shows the shape, not a real project decision:
- Title: ADR-012: Move invoice generation to a queued worker
- Status: Accepted, 2026-03-14
- Context: Invoice generation runs inside the checkout request. Peak-hour timeouts have increased, and the PDF renderer is the slowest step.
- Requirements: Checkout responses under two seconds at the 95th percentile. Invoices delivered within ten minutes of payment. No loss of invoice data if a worker fails.
- Options: (a) keep the status quo and add capacity; (b) move rendering to an asynchronous queue with retries; (c) move rendering to a third-party service.
- Decision: Option (b).
- Rationale: Option (a) fails the latency requirement at peak. Option (c) fails the data-residency constraint in the context section. Option (b) meets both, with the cost of a new queue to operate.
- Consequences: Failed jobs need a dead-letter process. Customer support must learn to explain the delay. Revisit if the queue volume exceeds the planned capacity.
Notice what the record does not say. It does not describe the worker’s code, and it does not claim the approach is best in general. It explains why it was best for these requirements, which is what a future rewrite team needs.
Comparing options fairly
When two or more real options exist, compare them against the same set of criteria. The useful criteria are the requirements and constraints each option must satisfy, the structural impact, the effect on quality attributes such as security, reliability, or availability, coupling and dependencies, implementation and operational cost, and how hard the decision is to reverse.
Rank #2
Reversibility deserves special attention. A choice that can be undone in a sprint is a different kind of decision from a choice of data store that every service depends on. The official guidance does not prescribe a universal weighted scorecard, and a numeric score can make a weak comparison look rigorous. Use whatever comparison format helps the team reason clearly, and state the judgments behind it.
Free tools Windows power users keep installed
One-click scans. No signup required.
Where ADRs should live
Next to the code
Google Cloud recommends keeping ADRs close to the application code, ideally in the same version control system, so that repository history records how each one changed. Microsoft’s engineering guidance describes decision logs and ADRs as searchable, version-controlled records for the same reason.
In a wiki or shared document
Google Cloud also accepts a shared document or internal wiki when the audience is wider than the engineering team. The trade-off is that a wiki page is easier for non-engineers to read but drifts from the code it describes unless someone links the two.
Rank #3
Ownership and review
Choose one canonical location and link to it from the project’s main documentation. Name an owner for each record area and agree who reviews a proposed ADR before it is accepted. Without clear review, ADRs tend to be written after the fact and do not record the options that were actually considered.
When a decision changes
An ADR is a record of what was decided at a point in time. Do not edit an accepted record to match the current system. AWS guidance treats an accepted ADR as immutable and says a later accepted ADR supersedes it. The process is:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- Write a new ADR with the new decision, its context, and why the old decision no longer fits.
- Mark the old record as superseded and link it to the new one.
- Link the new record back to the old one, so a reader following either path reaches the other.
- Keep both records. The old one still explains the architecture that existed before the change.
Revisit records when requirements, technology, or constraints change materially. You do not need to rewrite every old record to match the latest state, and doing so would erase the reasoning that explains how the system got there.
Rank #4
ADRs are not the whole architecture
A decision log answers why. Readers who need to understand what exists, how components connect, and where the system runs need architecture views and deployment diagrams. Google Cloud’s Well-Architected Framework warns that overly complex architecture is difficult to understand and manage. Use ADRs to explain the important choices, and keep the diagrams focused on the parts a newcomer must see first.
Keeping records from being abandoned
A common complaint in engineering forums is that architecture documents are written once and then left to rot within a few months. Several practices reduce that risk, based on the official guidance and the mechanics of the format:
- Attach ADRs to pull requests. If a change introduces a new dependency or interface, the review should ask whether an ADR exists or is needed.
- Keep records short. A record that takes an hour to write will not be written. Focus on the decision and its reasoning.
- Write one record per decision. Large combined documents are harder to supersede and harder to keep current.
- Review on a schedule tied to change. Revisit records when a requirement or dependency changes, not on an arbitrary calendar.
What the evidence does and does not establish
The guidance on ADRs is largely prescriptive: it describes what a good record contains and how it should be maintained. Google Cloud’s ADR page, which explains use cases, audience, format, and storage, was last reviewed in August 2024 according to its own metadata. The AWS Prescriptive Guidance and the Microsoft Azure Well-Architected Framework describe the same core practice with consistent emphasis on context, rationale, and consequences.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Microsoft’s Azure Well-Architected Framework puts the case directly: “Your architecture is the accumulation of its decisions, so the ADR is effectively a record of how and why the system came to be its current shape.”
No widely cited, verified statistic measures how much ADRs improve a rewrite or reduce defects. Be wary of articles that attach a percentage to the practice. The defensible claim is narrower: a written record of the options and reasoning gives a rewrite team something to test its assumptions against, and it stops the team from repeating a rejected option without knowing it was rejected.
Finally, the practice does not require any paid product. An ADR can be a Markdown file in the repository, and the discipline matters more than the tooling.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
