Have you ever asked your self the question: "Why did we do it like this"? I have, many times, when I revisit places in the code. We make decisions on a daily basis on how to solve things, some bigger then others. At some point later we come back to it and can't recount why we thought it a good idea at the time. For smaller design decisions this is sometimes OK. But for things that affects our architecture we'd often like to know why.

For some time now there has been a pattern for this. It's called Architecture Decision Record. As far as I can tell Michael Nygard identified the pattern in 2011. The blog post can be found here. It has since come up on Thoughtworks Technology Radar and ended up in the adopt section.

The idea is pretty simple. You create a light weight document, like a markdownd file, which you store close to the source of the decision, in the code base. It is structured much as a pattern, with context, decision, status and consequences. Michael Nygard describes the format really nicely in his post, using the format itself. There are several other variants of the ADR format, and you should use one that fits your need.

Here are some useful links to resources on ADRs:

• adr.github.io - a GitHub organisation around ADRs with a lot of very useful stuff.
• A compilation of different ADR formats.
• adr - a command line tool to work with ADRs that offers functions such as create, update and supersede with automatic numbering. By Nat Pryce.
• How Reverb.com has done it.
• Structurizr, Simon Brown's C4 architecture modeling tool, also offers support for ADRs.

I introduced ADRs into our organisation a bit more then a year ago and it is providing us with a lot of value.