Architecture Decision Records (ADRs)

"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."

Definition

An ADR or "Architecture Decision Record" is a method of recording and presenting proposed changes of system architecture to the team for review. Regardless of whether the changes are accepted, a record is produced to document the proposal, problem, outcome and explanation of the decision-making process. Once submitted, an ADR is treated as a forum for team discussion rather than just as a decision on whether to implement the proposed architectural changes.

The routine penning of ADRs creates a formalized way to document not just what we're doing, but why. Furthermore, ADRs are not alterable once published, though previous ADRs will be superseded by current ones. By following this process we create a clear history of how and why our methods have shifted overtime for you and any stakeholders to review.

Process

ADRs are created within the context of project based work. While you are working you may realize that a major tool you are using will no longer be supported in the next couple of years, or that a bug discovered by QA requires an infrastructural change to code-design for your product to function. Either of these situations will require an architectural decision to be made that will impact your teammates and the product you're working on. This will be your cue to begin the ADR process.

Once an ADR has been presented via Pull Request, the team will reach a consensus about their willingness to adopt the solution proposed by the author. Each ADR should be written as a means of best addressing the inciting issue, not as an advertisement for a shiny new tool you want to try. At the end of the day, the Project Lead has the ultimate say on whether an ADR will be accepted, rejected, or put on hold.