ADR: The post that explains why its architecture is designed this way

Architecture Decision Records were created for software—but have evolved into Any Decision Records. A comprehensive guide on how to document important decisions in short, versioned, and forget-proof documents.

Every codebase, every marketing process, and every operation carries an invisible layer: the set of decisions that led everything to turn out the way it is. You can read the code. The decision behind it—almost never. Six months later, no one remembers why the message queue replaced the synchronous call, why the attribution model changed, or why that vendor was dropped. Newcomers are left with only two bad options: accept the decision without understanding it, or reverse it without understanding it. ADR exists to create a third option.

What is an ADR?

An ADR (Architecture Decision Record) is a short document that captures a single decision relevant to a product or system, along with the context in which it was made and its implications. The most widely accepted definition is Martin Fowler’s: a document that should be only a few pages long and contain the decision, the context, and the significant ramifications—without becoming a complete description of the system.

The collection of all ADRs for a project forms its decision log—a sort of logbook that allows you to reconstruct a system’s history by reading the entries in order. The engineering documentation is deliberately minimal: short text, in Markdown or AsciiDoc, versioned along with the code.

The most subtle—and most valuable—point is that writing an ADR serves two purposes at once. It acts as a record, so that months or years from now, someone will understand why the system is designed this way. And it serves as a thinking tool: the act of writing forces the team to make trade-offs explicit, and it often brings differences of opinion to the surface so they can be discussed before the code is written.

Vocabulary: AD, ADR, ADL, ASR

The community focused on this topic has standardized four acronyms that are worth knowing, because they appear in almost all the literature.

• AD — Architectural Decision. A well-justified design choice that meets a relevant requirement (functional or non-functional).
• ADR — Architecture Decision Record. The document that captures an AD and the reasoning behind it.
• ADL — Architecture Decision Log. The collection of all ADRs for a project or organization.
• ASR — Architecturally Significant Requirement. A requirement that has a measurable impact on the system's architecture and quality.

All of this falls under the umbrella of Architectural Knowledge Management (AKM). The good news: you don’t need to memorize any of this to get started. All you need is a text file and the discipline to write it down at the moment the decision is made.

The story: from Nygard to “Any Decision Record”

The term was coined by Michael Nygard in November 2011, in a post titled “Documenting Architecture Decisions,” written while he was working at the consulting firm Relevance (later Cognitect). Nygard didn’t invent the idea of a decision log—he drew inspiration from Philippe Kruchten’s decision logs and the writing style of software patterns—but he advocated for something new: a lightweight document focused on the decision itself, compatible with agile methods.

From there, the format evolved in stages:

In 2012, Olaf Zimmermann introduced the Y-Statements (or (WH)Y-statements)—an entire decision encapsulated in a single structured sentence, created because project sponsors were asking for “one decision per slide.”

In 2017, MADR (Markdown Architectural Decision Records) was created by Oliver Kopp and Olaf Zimmermann, transforming the format into Markdown sections—which are easier to read and version control than the long sentence of the Y-Statement.

And here’s the most interesting conceptual shift. In 2022, in version 3.0, the MADR project was renamed from “Markdown Architectural Decision Records” to “Markdown Any Decision Records,” in line with the informal movement dubbed “ADR = Any Decision Record?” The premise: there is an endless debate about what is “architecturally significant”—so, rather than quibbling over that boundary, it’s better to acknowledge that any important decision deserves to be recorded in a structured way.

A nuance that almost every article gets wrong

In 2024, version 4.0 of MADR was renamed “Markdown Architectural Decision Records.” The acronym remains MADR, and the template continues to serve as a way to document any decision—only the label has changed. In other words, “Any Decision Record” is less of a product and more of a philosophy of use.

Why Use It — and an Honest Caveat

There are four benefits that are reported most consistently:

• Preserve the "why," not just the "what." A pull request title states what has changed. The ADR explains why that was the right solution at the time, what constraints applied, and what was ruled out.
• Speed up onboarding. Knowledge that is typically "institutional" and resides in the minds of only a few becomes something that can be read in chronological order.
• Avoid blind acceptance and reversal. Nygard’s original goal: those who come later don’t have to either accept or overturn a decision without understanding the reasoning behind it.
• Resilience and traceability. The log shows how the system and its trade-offs have evolved over time as the business changes.

The practice carries market weight. The ThoughtWorks Technology Radar placed “Lightweight Architecture Decision Records” in the Adopt ring—its strongest recommendation. AWS recommends ADRs in its Prescriptive Guidance, and the Azure Well-Architected Framework also highlights them.

“Excessive documentation can be replaced by readable code and tests. But in a world of evolutionary architecture, certain design decisions need to be documented—for the future team and for external oversight.”—paraphrase of the “Adopt” verdict from the ThoughtWorks Technology Radar

Anatomy of an ADR

Nygard’s original template is minimalist and remains the most widely used. It essentially consists of five parts.

A golden rule of writing: follow the inverted pyramid of journalism—put the most important information first. Anyone opening the document should understand the decision within the first few lines and only delve into the details if necessary. For the context section, it’s worth quoting Nygard’s description: the “forces at play, including the technological, political, social, and local aspects of the project.”

Status and Immutability

Here’s the key difference between a reliable log and a folder of drafts: an accepted ADR is immutable. Only its status changes. If reality changes, you don’t rewrite the old record—you create a new ADR that replaces the previous one, and mark the old one as “replaced,” with a link to its successor.

Why? Because that way, the record never becomes “outdated.” Even a decision that is no longer valid today was once true—and that dated truth is precisely the information you want to preserve.

The Three Essential Templates

There are dozens of formats—Joel Parker Henderson’s repository includes more than twenty. But in practice, three of them cover 95% of the cases.

Template	Form	It shines when…
Nygard	Short sections: Title, Status, Background, Decision, Consequences.	You want the minimum viable version and a commit message that’s easy to distinguish in Git.
MADR	Markdown with YAML; adds “Options Considered” with pros and cons, decision factors, and confirmation. Available in full and minimal versions.	The decision involves real alternatives that need to be compared side by side.
Y-Statement	A structured sentence: context → concern → choice → to achieve → by accepting → because.	You need something that can be presented “on a slide” to management.

The Y-Statement Template

It’s worth keeping the structure, because it’s a great mental exercise even when you use a different format:

# Y-Statement (Zimmermann)
In the context of ,
facing ,
we decided on 
and ruled out ,
to reach ,
accepting ,
because .

As a historical footnote: there is even a variant of YAML today (called YADR), designed to be processed by tools, and the international standard ISO/IEC/IEEE 42010 suggests nine pieces of information for recording decisions.

Two complete examples

Enough theory. Let’s look at the same idea applied to two different areas: a software decision (Nygard format) and an operations/RevOps decision (MADR format)—to illustrate how ADR moves beyond architecture and becomes Any Decision Record.

Beyond Architecture: Any Decision Record

Once the team gets used to documenting decisions, the format naturally spreads beyond engineering. MADR itself affirms this premise: since there is endless debate about what is “architecturally significant,” it is best to document any important decision in a structured way.

This isn’t just a theory—there are specific precedents. ThoughtWorks documented its Design System Decision Records: borrowing the idea of ADRs to document design system decisions with research and experiment results, which reduced onboarding time and aligned teams. This is precisely the path the next three sections take—moving beyond engineering and adapting this approach to marketing, sales, and process decisions.

The Business Decision Log

Marketing, sales, and operations teams suffer from the same amnesia as engineering—only worse, because almost nothing is versioned. Why did the standard discount become 15%? Why did we stop investing in that channel that seemed to be doing well? What was the definition of MQL before someone changed it in the middle of a meeting? This knowledge usually resides in the minds of two or three people and disappears along with them. The Business Decision Record—let’s call it BDR—is the same as an ADR, with the terminology adjusted to be more accessible to non-technical audiences.

There are few changes to the technical format, but they matter. Business decisions typically involve more people and a metric to track. So the template gains two fields—who made the decision and who was consulted, and which metric will indicate whether the decision was correct—and retains everything else, including the golden rule: an accepted record is immutable; if it changes, a new one is created to replace the previous one.

Where to store them when the team isn’t technical. Developers leave ADRs in Git, alongside the code. For marketing and sales, this usually creates more friction than value. Use a database in Notion or Confluence, or a folder in Google Drive with one document per decision and a numbered index. The format is secondary; what’s essential is: one decision per entry, sequential numbering, immutability, and a link from the place where the decision is applied—the dashboard, the playbook, or the field description in the CRM.

Decision Tree by Area

Not every choice becomes a record—only those that “carry weight,” the ones someone will question down the road. These are the most common candidates outside of engineering, along with the metric that’s typically at stake:

Area	Decisions Worth Noting	In-Game Metrics
Marketing	Attribution model; budget reallocation across channels; campaign naming convention; positioning/message pivot; selection of an automation platform.	CAC, ROI by channel, conversion rate.
Marketing / Sales	Discount policy; pricing and bundling; definition of ICP; segmentation and territories; change in the commission plan.	Average ticket, win rate, sales cycle, CAC payback.
RevOps / Processes	SLA and handoff between marketing and sales; lead routing rules; definition of funnel stages in the CRM; approval workflow; data governance.	MQL conversion rate, time to first contact, funnel leakage.
Product / Pricing	Release scope; billing model; what’s included in Plan X vs. Plan Y; discontinuing a feature.	NRR, churn, growth rate.
Data / Tools	Supplier selection (CRM, CDP, BI); single source of truth for a metric; stack consolidation.	Cost per seat, adoption, data quality.

Three Business Decisions in Practice

The same criteria, applied to three decisions that every go-to-market team ends up making—and almost never documents.

Why This Is a Sign of RevOps Maturity

A predictable funnel depends on consistent decisions—and decisions are only consistent when someone can confidently explain why the current rule exists. The decision log transforms fragile “institutional knowledge” into an asset that survives team turnover, onboarding, and the next tool switch.

Tools

You don’t need any software to get started—a text editor and the right folder are all you need. But as the log grows, some tools can be helpful:

• adr-tools — Bash scripts by Nat Pryce for creating and managing ADRs in the Nygard format. The classic starting point.
• Log4brains — docs-as-code knowledge base: you write ADRs in the editor, and the tool publishes a static website with a timeline and search functionality. Runs on npm install -g log4brains and log4brains init.
• ADR Manager — a VS Code plugin and web app (connects to a GitHub repository) for creating and editing MADRs using a form.
• dotnet-adr · pyadr — CLIs for the .NET and Python ecosystems.
• adr.zone — a web generator that supports multiple formats (Nygard, MADR, Y-Statement).
• Intelligence — Incuca’s AI-first software for RevOps teams, designed to document decisions and track metrics and results in real time

Best practices and anti-patterns

Do

• Write it down right when you make the decision, not weeks later—the context fades quickly.
• Record the decisions "that carry weight," not the trivial ones or the cosmic ones. "We chose Tailwind over Bootstrap" rarely matters; "we store session state in the database instead of in memory" matters a lot.
• Use pull requests for review. The proposed ADR is submitted as a PR; the discussion takes place there; merging into the main branch means "accepted."
• Code links to the ADR. A short comment at each architectural "seam," pointing to the record, makes the document appear exactly when it's needed.

Avoid

• Turn the ADR into a changelog. It doesn't replace good commit messages or record every little change.
• Rewrite accepted records. Has the decision changed? Create a new ADR, and mark the old one as superseded.
• "Documentation theater." Without a review schedule and without the team's trust, the log becomes write-only and dies. The difference between those who maintain ADRs for years and those who abandon them isn't the template—it's the operation.

AI: Write, Search, and Don’t Get Overwhelmed

The two main reasons a team doesn’t keep decision logs have always been: writing them is a hassle, and finding the right log later is even more of a hassle. Generative AI tackles exactly these two issues—and that’s why it changes the economics of the practice. But it’s important to distinguish between what it solves and what it doesn’t, because that’s where the pitfall lies.

Axis 1 — Writing: From the “real kernel” to the draft

The approach that has worked isn’t to ask, “Write a record from scratch,” but rather to start with a single sentence—the real core: "decidimos X porque Y" — and letting the AI expand it into the full report using its template. Agents can read code, a pull request diff, a meeting transcript, or a Slack thread and return a first draft with context, options, and consequences already filled in. In the business world, this means turning Friday’s RevOps call into a BDR draft before the context fades away.

Axis 2 — Search: this is where “too much documentation” stops being a problem

This is the point you raised, and it’s the most underestimated one. The fear of maintaining a large log has always been: “No one is going to read 200 records.” With enhanced retrieval (RAG) on the log, you don’t read it—you query it. “Why did we change the attribution model?” returns the two or three entries that matter, along with the reasoning, instead of an intimidating folder. The volume ceases to be a liability and becomes a searchable asset. Too much documentation only becomes a problem when the only way to access it is by reading everything.

It’s a two-way street: the log also feeds the AI

There’s an elegant symmetry here. A well-maintained decision log is exactly the kind of reliable, dated source that helps assistants and code agents make better decisions—it’s high-quality context, not noise. By 2026, this had become a topic of open debate: the decision log (the historical, passive “why”) coexists with instruction files for agents, such as AGENTS.md (the active “what needs to be true”). They do not compete: the log explains the choice; the instruction file ensures the AI adheres to it in practice.

The Trap

The bottleneck of good documentation has never been typing—it’s been thinking. Writing forced the team to confront trade-offs and bring disagreements to the surface. If AI writes and no one reviews it, you trade “too little documentation” for “plausible but empty documentation”—and, at scale, this is the documentation charade from the previous section, only automated and faster. The rule: AI drafts and revises; humans decide, confirm, and sign off. It’s even worth noting who made the decision—a person or an agent.

Note that the discipline changes form; it doesn’t disappear. Before, the work was writing. Now that content generation has become inexpensive, the work is curation: deciding what deserves to be recorded, confirming the reasoning, and marking what has been surpassed. AI doesn’t eliminate judgment—it focuses it on the part that has always mattered.

How to Get Started in 5 Steps

1. Write ADR-0001 about adopting ADRs. Seriously: the first log entry is usually the decision to use ADRs. This already tests the format and documents the choice itself.
2. Choose a template. Start with Nygard (minimal) or MADR minimal (if you frequently compare options). You can switch later.
3. Define the location. Create docs/decisions/ in the main repository and combine the sequential numbering.
4. Set up the process. Proposed ADRs are submitted via PR; reviewed by those affected; merge = accepted. Set aside 15 minutes during a recurring meeting to review the "proposals."
5. Make your first real decision count. Pick a choice that the team will question six months from now and record it today. A log with five good entries is already better than nothing.

Rule of thumb

If, six months from now, someone asks, “Why on earth is this the way it is?”, the answer should be just a search away in the repository. That’s the test to determine whether a decision warrants an ADR.

Frequently Asked Questions

Start small. Open a file, type ADR-0001, and make sure the next “Why is it like this?” question has an answer. The rest is just repetition.

From Unplanned Decisions to Predictable Operations

A memory-independent funnel doesn’t happen by chance—it’s built. InCuca helps marketing and sales teams transform fragile knowledge, trapped in the minds of a few, into a documented, automated, and AI-ready RevOps operation. From attribution to lead scoring, from the handoff between marketing and sales to pricing: we structure the decisions that underpin your funnel and build the automation that keeps them alive.

Want to stop rethinking the same things every quarter? Let’s talk →

Sources and Further Reading

References consulted · accessed in June 2026

1. Michael Nygard. “Documenting Architecture Decisions”—the 2011 essay that coined the term.
2. Martin Fowler. Architecture Decision Record (bliki).
3. ADR GitHub organization. adr.github.io — definitions, templates, and tools.
4. MADR: Markdown Architectural/Any Decision Records and release history.
5. Olaf Zimmermann. Architectural Decisions — The Making Of and Y-Statements.
6. ThoughtWorks Technology Radar. Lightweight ADRs (Adopt) and Design System Decision Records.
7. Red Hat. Why You Should Be Using Architecture Decision Records.
8. GDS Way. Documenting architectural decisions.
9. Thomas Vaillant. Log4brains — a tool for managing and publishing ADRs.
10. Joel Parker Henderson. Collection of ADR templates and examples.
11. Software Improvement Group. Using ADRs to guide your architecture choices.
12. Hidekazu Konishi. ADRs: Templates and Operational Patterns.