7/15/24, 1:59 PM dassiorleando/architecture-decision-record: Architecture decision record (ADR) examples for software planning, IT leadership, …

dassiorleando /
architecture-decision-record

Code Pull requests Actions Projects Security Insights

Architecture decision record (ADR) examples for software planning, IT leadership, and template documentation

0 stars 2.4k forks 2 watching 1 Branch 0 Tags Activity

Public repository · Forked from joelparkerhenderson/architecture-decision-record

1 Branch 0 Tags Go to file t Go to file Add file Code

This branch is 124 commits behind joelparkerhenderson/architecture-decision-record:main .

joelparkerhenderson Add "A Skeptic’s Guide to Software Architecture Decisions"

33c7393 · last year

doc Add AWS prescriptive guidance for … 2 years ago

examples fix typo: closure -> clojure 2 years ago

templates Use secure link last year

README.md Add "A Skeptic’s Guide to Software … last year

README

Architecture decision record (ADR)

An architecture decision record (ADR) is a document that captures an important architecture decision made
along with its context and consequences.

Contents:

What is an architecture decision record?

How to start using ADRs
How to start using ADRs with tools
How to start using ADRs with git
ADR file name conventions
Suggestions for writing good ADRs
ADR example templates
Teamwork advice
For more information

Templates:

Decision record template by Jeff Tyree and Art Akerman

https://github.com/dassiorleando/architecture-decision-record 1/7
7/15/24, 1:59 PM dassiorleando/architecture-decision-record: Architecture decision record (ADR) examples for software planning, IT leadership, …

Decision record template by Michael Nygard

Decision record template for Alexandrian pattern
Decision record template for business case
Decision record template for MADR
Decision record template using Planguage
Decision record template by Paulo Merson
Decision record template by EdgeX

Examples:

CSS framework
Environment variable configuration
Metrics, monitors, alerts
Microsoft Azure DevOps
Monorepo vs multirepo
Programming languages
Secrets storage
Timestamp format

What is an architecture decision record?

An architecture decision record (ADR) is a document that captures an important architectural decision made
along with its context and consequences.

An architecture decision (AD) is a software design choice that addresses a significant requirement.

An architecture decision log (ADL) is the collection of all ADRs created and maintained for a particular
project (or organization).

An architecturally-significant requirement (ASR) is a requirement that has a measurable effect on a software

system’s architecture.

All these are within the topic of architecture knowledge management (AKM).

The goal of this document is to provide a fast overview of ADRs, how to create them, and where to look for
more information.

Abbreviations:

AD: architecture decision

ADL: architecture decision log

ADR: architecture decision record

AKM: architecture knowledge management

ASR: architecturally-significant requirement

How to start using ADRs

To start using ADRs, talk with your teammates about these areas.

Decision identification:

https://github.com/dassiorleando/architecture-decision-record 2/7
7/15/24, 1:59 PM dassiorleando/architecture-decision-record: Architecture decision record (ADR) examples for software planning, IT leadership, …

How urgent and how important is the AD?

Does it have to be made now, or can it wait until more is known?

Both personal and collective experience, as well as recognized design methods and practices, can assist
with decision identification.

Ideally maintain a decision todo list that complements the product todo list.

Decision making:

A number of decision making techniques exists, both general ones and software architecture specific
ones, for instance, dialogue mapping.

Group decision making is an active research topic.

Decision enactment and enforcement:

ADs are used in software design; hence they have to be communicated to, and accepted by, the
stakeholders of the system that fund, develop, and operate it.

Architecturally evident coding styles and code reviews that focus on architectural concerns and
decisions are two related practices.

ADs also have to be (re-)considered when modernizing a software system in software evolution.

Decision sharing (optional):

Many ADs recur across projects.

Hence, experiences with past decisions, both good and bad, can be valuable reusable assets when
employing an explicit knowledge management strategy.

Group decision making is an active research topic.

Decision documentation:

Many templates and tools for decision capturing exist.

See agile communities, e.g. M. Nygard's ADRs.

See traditional software engineering and architecture design processes, e.g. table layouts suggested by
IBM UMF and by Tyree and Akerman from CapitalOne.

Decision guidance:

The steps above are adopted from the Wikipedia entry on Architectural Decision

A number of decision making techniques exists, both general ones and software architecture specific
ones, for instance, dialogue mapping.

How to start using ADRs with tools

You can start using ADRs with tools any way you want.

For example:

If you like using Google Drive and online editing, then you can create a Google Doc, or Google Sheet.

If you like use source code version control, such as git, then you can create a file for each ADR.

https://github.com/dassiorleando/architecture-decision-record 3/7
7/15/24, 1:59 PM dassiorleando/architecture-decision-record: Architecture decision record (ADR) examples for software planning, IT leadership, …

If you like using project planning tools, such as Atlassian Jira, then you can use the tool's planning
tracker.

If you like using wikis, such as MediaWiki, then you can create an ADR wiki.

How to start using ADRs with git

If you like using git version control, then here is how we like to start using ADRs with git for a typical
software project with source code.

Create a directory for ADR files:

$ mkdir adr

For each ADR, create a text file, such as database.txt :

$ vi database.txt

Write anything you want in the ADR. See the templates in this repository for ideas.

Commit the ADR to your git repo.

ADR file name conventions

If you choose to create your ADRs using typical text files, then you may want to come up with your own ADR
file name convention.

We prefer to use a file name convention that has a specific format.

Examples:

choose-database.md

format-timestamps.md

manage-passwords.md

handle-exceptions.md

Our file name convention:

The name has a present tense imperative verb phrase. This helps readability and matches our commit
message format.

The name uses lowercase and dashes (same as this repo). This is a balance of readability and system
usability.

The extension is markdown. This can be useful for easy formatting.

Suggestions for writing good ADRs

Characteristics of a good ADR:

Rational: Explain the reasons for doing the particular AD. This can include the context (see below), pros
and cons of various potential choices, feature comparions, cost/benefit discussions, and more.

https://github.com/dassiorleando/architecture-decision-record 4/7
7/15/24, 1:59 PM dassiorleando/architecture-decision-record: Architecture decision record (ADR) examples for software planning, IT leadership, …

Specific: Each ADR should be about one AD, not multiple ADs.

Timestamps: Identify when each item in the ADR is written. This is especially important for aspects that
may change over time, such as costs, schedules, scaling, and the like.

Immutable: Don't alter existing information in an ADR. Instead, amend the ADR by adding new
information, or supersede the ADR by creating a new ADR.

Characteristics of a good "Context" section in an ADR:

Explain your organization's situation and business priorities.

Include rationale and considerations based on social and skills makeups of your teams.

Include pros and cons that are relevant, and describe them in terms that align with your needs and
goals.

Characteristics of good "Consequences" section in an ADR:

Explain what follows from making the decision. This can include the effects, outcomes, outputs, follow
ups, and more.

Include information about any subsequent ADRs. It's relatively common for one ADR to trigger the need
for more ADRs, such as when one ADR makes a big overarching choice, which in turn creates needs for
more smaller decisions.

Include any after-action review processes. It's typical for teams to review each ADR one month later, to
compare the ADR information with what's happened in actual practice, in order to learn and grow.

A new ADR may take the place of a previous ADR:

When an AD is made that replaces or invalidates a previous ADR, then a new ADR should be created

ADR example templates

ADR example templates that we have collected on the net:

ADR template by Michael Nygard (simple and popular)

ADR template by Jeff Tyree and Art Akerman (more sophisticated)

ADR template for Alexandrian pattern (simple with context specifics)

ADR template for business case (more MBA-oriented, with costs, SWOT, and more opinions)

ADR template MADR (more Markdown)

ADR template using Planguage (more quality assurance oriented)

Teamwork advice
If you're considering using decision records with your team, then here's some advice that we've learned by
working with many teams.

You have an opportunity to lead your teammates, by talking together about the "why", rather than
mandating the "what". For example, decision records are a way for teams to think smarter and communicate
better; decision records are not valuable if they're just an after-the-fact forced paperwork requirement.

https://github.com/dassiorleando/architecture-decision-record 5/7
7/15/24, 1:59 PM dassiorleando/architecture-decision-record: Architecture decision record (ADR) examples for software planning, IT leadership, …

Some teams much prefer the name "decisions" over the abbreviation "ADRs". When some teams use the
directory name "decisions", then it's as if a light bulb turns on, and the team starts putting more information
into the directory, such as vendor decisions, planning decisions, scheduling decisions, etc. All of these kinds
of information can use the same template. We hypothesize that people learn faster with words ("decisions")
over abbreviations ("ADRs"), and people are more motivated to write work-in-progress docs when the word
"record" is removed, and also some developers and some managers dislike the word "architecture".

In theory, immutability is ideal. In practice, mutability has worked better for our teams. We insert the new
info the existing ADR, with a date stamp, and a note that the info arrived after the decision. This kind of
approach leads to a "living document" that we all can update. Typical updates are when we get information
thanks to new teammates, or new offerings, or real-world results of our usages, or after-the-fact third-party
changes such as vendor capabilties, pricing plans, license agreements, etc.

For more information

Introduction:

Architectural decision (wikipedia.org)

Architecturally significant requirements (wikipedia.org)

Templates:

Documenting architecture decisions - Michael Nygard (thinkrelevance.com)

Markdown Architectural Decision Records (adr.github.io)

Template for documenting architecture alternatives and decisions (stackoverflow.com)

In-depth:

ADMentor XML project (github.com)

Architectural Decision Guidance across Projects: Problem Space Modeling, Decision Backlog
Management and Cloud Computing Knowledge (ifs.hsr.ch)

The Decision View's Role in Software Architecture Practice (computer.org)

Documenting Software Architectures: Views and Beyond (resources.sei.cmu.edu)

Architecture Decisions: Demystifying Architecture (utdallas.edu)

ThoughtWorks Technology Radar: Lightweight Architecture Decision Records (thoughtworks.com)

A Skeptic’s Guide to Software Architecture Decisions (infoq.com)

Tools:

Command-line tools for working with Architecture Decision Records

Command line tools with python by Victor Sluiter

Company-Specific Guidance:

Amazon: AWS Prescriptive Guidance: ADR Process

GitHub: ADR GitHub organization

RedHat: Why you should use ADRs

https://github.com/dassiorleando/architecture-decision-record 6/7
7/15/24, 1:59 PM dassiorleando/architecture-decision-record: Architecture decision record (ADR) examples for software planning, IT leadership, …

Examples:

Repository of Architecture Decision Records made for the Arachne Framework

See also:

REMAP (Representation and Maintenance of Process Knowledge)

DRL (Decision Representation Language)

IBIS (Issue-Based Information System)

QOC (Questions, Options, and Criteria)

IBM’s e-Business Reference Architecture Framework

Releases

No releases published

Packages

No packages published

https://github.com/dassiorleando/architecture-decision-record 7/7