DEV Community

Cover image for Writing Architecture Decision Records
Carlos Cuesta
Carlos Cuesta

Posted on • Updated on • Originally published at


Writing Architecture Decision Records

An architecture decision record also known as ADR, is a document that captures an important architecture decision, including the context of how the decision was made and the consequences of that change.

What are the benefits?

Sharing context

ADRs capture a decision at the time it's being made. They're the outcome of all of those asynchronous discussions in Slack that'll be lost over time ⏰

When you materialize them into docs, you're allowing your future teammates, to get the context for this specific change. So they'll be able to understand the issues, the decision that was taken and the impact it had on the project.

Writing docs will help you and your future peers in the long run! πŸš€


Writing decisions leads the team to consensus and ensures that all the assumptions of a change are clear πŸ“.

This will have a positive impact after the architecture decision has been implemented. Everyone on the team will have a deep understanding which will help on moving forward faster with the new approach.

Writing ADRs

Define a template

When writing them, a common practice is to have a template to write ✍🏼 all the documents in the same way.

You'll find a lot of templates online, but here's the one I use it's very simple but easy to write.

# Title

- Date: DD/MM/YYYY
- RFC: <!-- Link to the RFC that ended up into the ADR -->

## Context

<!-- What is the issue that is motivating the decision or change? -->

## Decision

<!-- What is the change we're doing? -->

## Consequences

<!-- What becomes easier or more difficult because of this change? -->
Enter fullscreen mode Exit fullscreen mode

Store them next to the code

I believe that documentation should be next to the code to make it easy to contribute to it. Whenever you add an external tool you're increasing the complexity to contribute and reducing the visibility of the docs πŸ‘€.

The solution is simple, check out the ADRs into your project repository and keep things simple and clean ✨

I recommend you to create a folder πŸ“ where you store all the decision records, for example: docs/adrs/.

Use a naming convention

When saving the files use a naming convention


Write more ADRs 😜, if you're not doing it yet, it's never too late to start!

In my experience as a team grows larger and a codebase becomes more complex, architecture decision records are a great tool to help your current and future team ❀️

Top comments (2)

bolt04 profile image
David Pereira

Hi Carlos, great post πŸ‘. Do you know any public repos with examples of this? Actual real ADRs?

carloscuesta profile image
Carlos Cuesta

Hey! Thanks for the comment 😊

Here's a repo that includes some examples

Timeless DEV post...

Git Concepts I Wish I Knew Years Ago

The most used technology by developers is not Javascript.

It's not Python or HTML.

It hardly even gets mentioned in interviews or listed as a pre-requisite for jobs.

I'm talking about Git and version control of course.

One does not simply learn git