Summaries of artifacts, templates, practices, and techniques for agile architecting (DPR-mm) and service design (SDPR-nn).

DPR Git Pages HomeActivities Index

Activity/Technique: Architectural Decision Capturing

also known as: Decision Log(ging)


Each software system has an architecture, which is defined by the set of architectural decisions made. Hopefully, these decisions are made consciously and continuously, and consensus is reached about them. This decision making progress should be recorded to avoid knowledge vaporization.

Discussion: Not all organizations can or want to follow a “products over projects” philosophy; team members come and go, e.g., external consultants. Some of these tend to apply the “I know better, why haven’t you done this and that?” tactic when joining and forget to document their legacy when leaving. Keeping a decision log current is a good safety belt in such (and similar) situations.

Purpose (When to Use and When not to Use)

As a technical team lead (architect, lead developer, product manager), I want to keep track of the results of all architecture design activities in a compact and searchable form so that newcomers can get a quick overview of the key decisions made, and the entire team (and interested external stakeholders) has a single point of reference when making follow-on decisions.

There are no reasons not to capture decisions. Two variants exist, continuous architectural decision capturing and stage-based architectural decision capturing. A stage refers to a phase or iteration, for instance a sprint in Scrum and other agile methods.

Instructions (Synopsis, Definition)

Keep a log of architectural decisions in a single place that is accessible to the entire team.

This log can, for instance, be a team-wide source modeling or code repository, a project-wide wiki, or a shared office document (word processor, spreadsheet). As the first decision to be captured, select a verbosity level for the decision log:

The Five Steps of Decision Capturing: EC-ADR ("easy ADR")


An example of a minimal decision capture is:

ADR-001: We decided for MySQL as our relational database in the backend 
because this database has been approved strategically by our EAM group, 
has good tool support and sufficient performance under the workload that 
we expect from the user stories to be implemented in the next 10 sprints.

Page 18 in a SAGRA 2016 keynote features a medium-verbose ADR:

Exemplary Architectural Decision Record (ADR)

See this SATURN 2010 presentation for a full-fledged example (Page 14).

Benefits vs. Effort (Expected Benefits, Skill Levels)

There are few short-term incentives for decision capturing, which has been reported to pay off in the medium to long time. Many architects report that out of all views on software architecture they provide in their software architecture documents, the decision log has been read and commented on and appreciated the most. No special skills are required; anybody who can make a decision (or contribute to a collaborative decision making effort) should be able to capture the outcome and the supporting arguments.

Comparing the two common types of definition of software architecture (components and connectors vs. set of design decisions), one can view the latter as the software engineering/architecting process equivalent of event sourcing, with all its pros and cons.

Hints and Pitfalls to Avoid

Some additional rules of thumb are:

From a quality point view, look for accountability (of decision makers), consistency (between decisions, between decisions and implementation artifacts), and continuity (or currentness of the design artifacts).

See InfoQ/IEEE Software article “Sustainable Architectural Design Decisions” for more tips and tricks.

Origins and Signs of Use

Origins. AD capturing has been a key element in iterative and incremental SE methods such as (R)UP and IBM UMF (and its predecessors) since the late 1990s. For instance, OpenUP has the notion of an Architecture Notebook that calls for decision capturing with a justification as a mandatory element even in minimal project documentation. The term rationale also appears in one of the first articles that defined software architecture (by Perry/Woolf). Book authors have always seen decisions to take center stage in architecture design process; see, for instance, works by SEI authors including Attribute-Driven Design (ADD) 3.0, but also patterns books and supporting material such as this rambling on the Enterprise Integration Patterns website. George Fairbanks suggests a single-sentence decision outcome overview as part of his Architecture Haiku, also used by Michael Keeling here.

Around 2014, research sub-community jumped on the topic at conferences such as WICSA and workshops such as SHARK. Decision rationale also is a mandatory element in the ISO/IEC/IEEE 42010:2011, Systems and software engineering – Architecture description. The lean and agile communities talk about deferring decisions until the last (but not the least) responsible moment; for instance, Michael Nygard suggested the ADR format in November 2011. Many organizations and teams design their own templates, some of which are based on those in the literature; others are custom made, applying common sense and practices from other fields.

See the blog post“Architectural Decisions — The Making Of” for more history and context information.

Signs of Use. Filled out templates obviously indicate that decisions are made and captured explicitly. But informal justifications, for instance in the form of “we did this … because …” also qualify.

Involved roles:

Produced artifact:

Other Practices (Alternatives)

There are no alternatives, really. The emergent architecture community suggests not to make ADs consciously, but let the architecture emerge and evolve through frequent iterations including intense refactoring supported by measurements/experiments.

The Agile Alliance lists a Quick Design practice in its Agile Glossary. The outcome of such quick design sessions can be captured as an ADR in the decision log.

Agile Modeling has the notion of Architecture Envisioning, which yields strategic, high-impact decisions. Not even the most extreme agile team will replace is database paradigm, technology, and provider in each and every sprint.

More Information

See “Y-Statements” post on Medium and Slides 51 and 52 in this presentation for examples of good and bad justifications; for instance, “will look good on my CV” does not qualify as a sound decision rationale for a technology selection decision (although it is understandable to come up with such argument).

This website and this paper provide an overview of selected existing templates for AD capturing and decision logging (both lean and full-fledged).

The adr organization at GitHub also compiles AD templates, as well as tools and other resources.

See this SATURN 2013 BoF session report for a cost-benefit discussion and open research questions.

Finally, there is a proposal for “A Definition of Done for Architectural Decision Making”.

Data Provenance

title: "Design Practice Repository (DPR): Architectural Decision Capturing"
author: Olaf Zimmermann (ZIO)
date: "04, 21, 2021"
copyright: Olaf Zimmermann, 2020-2021 (unless noted otherwise). All rights reserved.
license: Creative Commons Attribution 4.0 International License