Architecture Decision Record

Architecture Decision Records capture major architectural decisions and related context, incl. criteria, rationale and consequences.

One of the fundamental laws of nature, is that everything changes. In the software engineering, business priorities, team structure, architecture, often change at faster pace than in many other domains.

To deal with some of these changes (e.g. onboarding new people, transitioning to new architecture, etc.), it is important to have organisational know-how / context in written form.

The purpose of Architecture Decision Record (ADR) is to capture major architectural decisions and related context, incl. criteria, rationale and consequences. It acts as snapshot of knowledge, environment and thinking at particular time.

Every ADR should consist of the following key sections:

Introduction

It should provide a very short summary for the reader to understand where the decision fits in overall scheme of things. It is not intended to be place for providing extensive context on the topic (That is the intention of RFC).

Decision Criteria

It should list criteria that are driving the decision. These should generally follow the Success Criteria from the RFC, however they can also include additional things like business / compliance requirements, etc.

Considered Options

It should provide a very short description of considered options (with links to more detailed explanation in the RFC).

Decision

It should provide a rationale behind decision.

Consequences

It should list potential consequences from making the decision.

The focus should not be on the structure but matter itself, i.e. what were driving criteria for the decision, considered options, decision and rationale behind it, and finally consequences.

Bonus: ADR template