Architecture Documentation with ADRs: A Practical Guide

An Architectural Decision Record (ADR) is a short document that captures one significant architectural decision, the context in which it was taken and the consequences the team accepted. A collection of ADRs forms the decision log of a project, and it is the most economical form of architecture documentation for explaining why a system has its present shape. This guide covers what an ADR contains, which template to adopt, how the process works in practice, where the records should live and how a company commissioning software can require them from a supplier.

TL;DR

• An ADR records a single architecturally significant decision with its context, alternatives, rationale and consequences. It is not a full description of the architecture.
• Three formats dominate: MADR, the Nygard structure and Y-Statements. Any of them works if the team applies it consistently.
• Store ADRs as Markdown files in version control next to the code, review them through pull requests, and treat accepted records as immutable: a changed decision produces a new ADR that supersedes the old one.
• Reserve ADRs for decisions that alter structure, quality attributes or integrations, or that are hard to reverse. A catalogue of trivial records is noise.
• When you commission software, ask for the decision log as a contractual deliverable, so that rationale survives staff changes and supplier changes.

Table of Contents

• What an ADR is, and what it is not
• Why decision records outperform voluminous documentation
• Which decisions deserve an ADR
• The content of a useful ADR
• Choosing a template: MADR, Nygard and Y-Statements
• The ADR process in practice
• Where the records should live
• A worked example
• Common failures and how to avoid them
• Requiring ADRs from a software supplier
• Our perspective
• How we can help
• FAQ
• Sources

What an ADR is, and what it is not

The ADR community project defines an architectural decision as a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. The ADR is the document that preserves that choice together with its justification. AWS prescriptive guidance describes the minimum sections as context, decision and consequences, and it adds a lifecycle with explicit statuses.

The distinction from other documents matters. An ADR is not a complete description of the architecture, and it is not a generic meeting minute. A component diagram tells a new engineer what exists; an ADR tells them why it exists and what was rejected. AWS stresses that the record concentrates on the reason for the decision rather than on how every detail was implemented. That separation allows new engineers, maintenance providers and business stakeholders to understand the rationale without reconstructing it from tickets, chat threads and commit histories.

Microsoft goes further and describes the ADR in its Azure Well-Architected guidance as one of the most important deliverables of an architect, because architecture is the accumulation of decisions. The value does not lie only in knowing which technology was chosen, but in making it verifiable how and why the system reached its current form.

Why decision records outperform voluminous documentation

Traditional architecture documents tend to fail in one of two ways. Either they are written once, at the start of a project, and drift away from the implementation within a few releases, or they are so extensive that nobody reads them. A decision log avoids both failure modes because each entry is small, dated and tied to a moment when something was actually decided.

For an organisation that commissions software, the consequences are practical. Consider a multi-tenant SaaS platform whose team chose a shared database with row-level tenant isolation rather than a database per tenant. Two years later, a new lead engineer, or a new maintenance supplier, proposes migrating to separate databases. Without a record, the discussion restarts from nothing and the earlier constraints (cost per tenant, expected tenant count, regulatory requirements) are rediscovered at the price of weeks of work. With a record, the proposal is judged against explicit assumptions, and the question becomes whether those assumptions have changed.

The ADR templates page recommends stating the options considered with their advantages and disadvantages, not only the selected solution. For decisions on stack, database, integration or deployment, this protects the company from reopening settled debates cyclically and makes the accepted trade-offs visible to people who were not in the room.

Which decisions deserve an ADR

Microsoft suggests that a record is warranted when a decision affects the structure of the system, affects qualities such as security, performance, availability or scalability, or is difficult to reverse. The same guidance warns against excess: an overly extensive catalogue produces noise and reduces the usefulness of the log.

A workable filter is to ask whether a competent engineer joining in a year would be surprised by the choice and would need the reasoning to maintain the system safely. The table below applies that filter to common situations.

The content of a useful ADR

The templates differ in headings, but the information they preserve is largely the same. For a project involving integrations, legacy modernisation or a multi-tenant SaaS platform, we recommend that every record states the following, in this order of reasoning: the problem and its context; the functional and non-functional requirements that bear on it; the constraints; the options considered; the criteria used to compare them; the decision; the positive and negative trade-offs; the residual risks; a plan to confirm the decision through tests or code review; and finally the owner, the date and the status.

Two elements are routinely omitted and are the ones that repay the effort most. The first is the residual risk: what could still go wrong, and what signal would indicate that the decision should be reviewed. The second is confirmation. The MADR template includes an explicit Confirmation section so that the team states how compliance with the decision will be verified, whether by an architectural test, a code review checklist or a deployment policy. A decision that cannot be verified tends to be forgotten.

Google Cloud lists the typical contents of a record as the problem, the main options, the decision and the motivation, which is consistent with the structure above. A short record of one page is normally preferable to a long one; the goal is that someone reads it.

Choosing a template: MADR, Nygard and Y-Statements

The ADR templates overview shows that many formats exist, including MADR, the Nygard structure and Y-Statements. There is no single correct choice, and the practical question is which one your team will actually complete.

Our experience is that the minimal MADR variant is a sound default for client projects, because the decision drivers and considered options sections force the discussion of alternatives, and the confirmation section links the record to the delivery process. Nygard remains an excellent choice for a very small team in its first months.

A note on standards. ISO/IEC/IEEE 42010:2022, the second edition published in November 2022, addresses the structure and expression of architecture descriptions for software, systems and enterprises. It defines requirements for frameworks, languages, viewpoints and model kinds, but it does not prescribe a specific format or medium for recording architecture. An organisation can therefore keep Markdown ADRs in Git, provided that the structure serves the stakeholders and viewpoints whose concerns the architecture description must address. If your sector or contract requires conformance with the standard, ADRs complement the viewpoint-based description rather than replace it, and they cover the dimension of rationale particularly well.

The ADR process in practice

The process described by AWS is a lifecycle, and it can be summarised in a sequence that a team can adopt within a single sprint.

First, a decision is identified and an owner is named. The owner is accountable for the record, not necessarily for the decision itself. Second, the owner drafts the ADR in the status Proposed, including the options and trade-offs. Third, the draft is reviewed by the engineers and stakeholders affected, and it is accepted, reworked or rejected. Fourth, the status, version, date and stakeholders are recorded. Fifth, if circumstances change, a new ADR is created that supersedes the earlier one, rather than editing history.

Microsoft recommends statuses such as Proposed, Accepted and Superseded, and advises starting the log when the workload begins and maintaining it throughout its life. In brownfield systems the log can also be built retroactively when the information is still available: interviewing the engineers who made the original choices, and recording them before they leave, is often the most valuable documentation exercise a legacy project can undertake.

Immutability is the rule that protects the log

The most important operating rule is that approved or rejected ADRs are treated as immutable. When requirements, constraints, costs or technology change, the team writes a new ADR linked to the previous one and marks the old record as superseded. Rewriting the original text retroactively destroys the decisional history and makes it harder to understand why the system changed. A rejected record is equally valuable, because it documents an option that was examined and why it was set aside, which prevents the same proposal from returning every quarter.

Typographical corrections and added links are acceptable. Changing the substance of what was decided is not.

Where the records should live

The most effective format is normally a Markdown file versioned alongside the code, not a document isolated in an administrative folder. Google Cloud recommends keeping ADRs in version control close to the relevant codebase, so that a reader who needs to understand a choice, such as a cloud topology or a regional cluster, can read the context and then follow a link to code and infrastructure. That proximity reduces the risk that documentation separates from implementation.

In a distributed or offshore engagement the repository becomes a single, verifiable source. Every ADR passes through a pull request, which gives a timestamped review trail, names the reviewers and lets the client observe the discussion. A wiki can offer a more accessible view for non-technical stakeholders, but it should be generated from or linked to the repository, not maintained as a competing copy. A convention such as a numbered file in a dedicated directory, for instance docs/adr/0007-message-broker-selection.md, keeps the log ordered and searchable.

A worked example

To illustrate the level of detail, consider a condensed record for an integration project in which a company must connect a legacy ERP to a new customer portal.

The context states that the ERP exposes only nightly batch exports and a fragile SOAP interface, and that the portal needs order status within a minute of a change. The requirements include near-real-time visibility and no additional load on the ERP during business hours. The constraints are that the ERP vendor will not modify the product and that the budget excludes replacing it. Three options are compared against criteria of latency, operational risk, cost and reversibility: direct polling of the SOAP interface, change-data-capture feeding a message broker, and a nightly batch with a manual refresh button. The decision selects change-data-capture with a broker, accepting higher infrastructure complexity as the negative consequence and gaining decoupling and replay capability as the positive one. The residual risk is dependency on database-level access that the ERP vendor could restrict. The confirmation plan is a contract test against the event schema and a load test during business hours. The record carries an owner, a date and the status Accepted.

Such a record fits on one page, yet it answers the question that a new engineer or a new supplier would otherwise spend days investigating.

Common failures and how to avoid them

The first failure is writing records after the fact for every minor choice, which turns the log into an archive nobody consults. The second is recording only the chosen option, which makes the document a justification rather than an analysis. The third is leaving records in a status of Proposed indefinitely, so that nobody knows what is in force. The fourth is detaching the records from the code, so that they are never updated when an implementation diverges. The fifth, specific to outsourced work, is accepting a large architecture document at the end of the project as a substitute for decisions captured while the work was happening, which tends to preserve volume rather than rationale.

The remedy for each is procedural and cheap: a threshold for what merits a record, a mandatory options section, a periodic review of open proposals, storage in the repository, and a delivery contract that names the decision log as a deliverable at each milestone.

Requiring ADRs from a software supplier

For a business owner or project manager who commissions software, the decision log is a means of retaining control. It makes the knowledge generated during the engagement a property of the client, independent of any individual engineer. In practice, three clauses are sufficient: that significant architectural decisions are recorded as ADRs in a repository the client can access; that records are reviewed before the corresponding implementation is merged; and that the log is delivered and kept current as part of maintenance. This also eases the transition if the maintenance responsibility later moves to an internal team or to another provider.

It is equally useful when the architecture already exists and nobody remembers the reasoning. A code audit combined with retroactive ADRs for the ten most consequential decisions gives a company a reliable baseline before it commits to modernisation or to a new integration.

Our perspective

We work with a small number of simultaneous projects, and clients speak directly to the engineers who design and build their software, without an account-management layer in between. That model makes decision records natural rather than bureaucratic: the person who weighs the options is the person who writes the record, so the rationale is captured at its source and not reconstructed by an intermediary.

We hold three convictions on the subject. The first is that an ADR must be written for the reader who arrives later, whether that is a future engineer, an auditor or the client’s next supplier. The second is that recommendations should be written down: every consulting engagement we deliver ends with a written recommendation, and ADRs are the same discipline applied continuously during delivery. The third is that independence of judgement shows in the options section. Because we have no vendor bias, we can record honestly why a technology was rejected, including technologies that we know well, which is precisely the information a client needs when the stack is chosen across areas such as Java and Jakarta EE, Spring Boot, Quarkus, Next.js or Angular, or when workloads are placed on Kubernetes and Red Hat OpenShift.

We also consider the repository the right place for the evidence. Peer-reviewed code and ADRs reviewed in the same pull request keep the explanation and the implementation in step, and make long-term maintenance cheaper for everyone involved.

— Pepe F.

How we can help

If you want a decision log established on a new product, or reconstructed for an existing system, our architecture and code audit work covers both, and you can see the full range on our services page. For organisations that need continuing senior technical judgement, our CTO subscription plans start with CTO Advisory from €1,800 per month, followed by Fractional CTO from €4,000 per month and CTO Partner from €7,500 per month. An initial assessment is available from €3,500 as a one-off engagement. Custom development, architecture and stack selection, AI and automation, and staff augmentation are quoted on request.

FAQ

What does ADR mean in software architecture?

ADR stands for Architectural Decision Record. It is a document that captures one significant architectural decision, the context, the alternatives, the rationale and the consequences. The set of records forms the decision log of the project.

Is there a standard ADR template?

No single template is mandatory. The most common are MADR, the Nygard structure (title, status, context, decision, consequences) and Y-Statements, all described on the ADR templates page. Choose the one your team will complete consistently, and keep the same format across the project.

Can we edit an ADR after it has been accepted?

Not in substance. If the decision changes, write a new ADR that supersedes the old one and mark the earlier record accordingly. Editing the original erases the history that explains why the system evolved.

Where should ADRs be stored?

In version control, as Markdown files near the code they concern, so that they are reviewed through pull requests and updated with the implementation. A wiki view can be added for non-technical readers, provided it is derived from the repository.

Does an ADR replace the full architecture description?

No. An ADR explains individual decisions, while an architecture description presents the structure of the system from several viewpoints. ISO/IEC/IEEE 42010:2022 does not prescribe a format, so the two can coexist, with the ADR log supplying the rationale.

Sources

• Architectural Decision Records (ADRs)
• ADR Templates
• ADR Template, MADR
• ADR process, AWS Prescriptive Guidance
• Maintain an architecture decision record, Microsoft Azure Well-Architected Framework
• Architecture decision records overview, Google Cloud Architecture Center
• ISO/IEC/IEEE 42010:2022, Architecture description

This article was produced with AI assistance and reviewed for accuracy. It is provided for general information only and is not professional advice.