Architecture Decision Record
To document or not to document? What to document? For whom? These questions spark heated debates within agile teams. Let’s take a step back and focus here on just one very specific aspect of the issue: an aspect that, to my knowledge, is generally agreed upon.
A tool to streamline your team’s decision-making
The Architecture Decision Record (ADR) is intended to document decisions regarding a product’s architecture, detailing the ins and outs of those decisions: contextual factors, uncertainties, and assumptions made as a result, and of course the various options under consideration along with their pros and cons. And, of course, the final decision.
The goal is to ensure that no fundamental decisions are made lightly, based on unsubstantiated intuition or personal preferences. We’re all too familiar with developers’ fascination with the latest trendy architecture or technology—which is inevitably touted as incredibly powerful but ends up dragging us down for years like a ball and chain: hello ES/CQRS, hello microservices.
Here are a few examples of topics that are worth documenting in an ADR:
- Choosing a communication pattern between contexts: orchestration vs. choreography (Event-Driven Architecture);
- Choosing a deployment model: modular monoliths vs. microservices;
- Choosing between a CRUD architecture, a hexagonal architecture, and a functional core/imperative shell;
- Choosing a testing strategy.
The ADR: For Greater Stability and Consistency
The benefit of this approach is that it prevents these issues from being reopened every few days—whether because of a new team member or because we’re facing the drawbacks inherent in the chosen option. A decision is never without drawbacks; it’s just that these drawbacks are known and accepted because they come hand in hand with greater benefits. All of this has been weighed and evaluated once and for all, so that as long as the underlying factors remain unchanged, there is no reason to question the decision; however, if an assumption is invalidated by experience, or if the context changes, the decision may be reconsidered.
Taking the time to record these decisions in an ADR also encourages teams to reach consensus on a wider range of topics, preventing individual developers from working in isolation according to their own preferences. Ideally, you shouldn’t be able to tell whether a piece of code was written by Paul or Paulette. This improves the consistency of the codebase, which makes future refactoring easier. For this reason, it’s often better to make a decision that we know isn’t ideal than to make no decision at all.
When to start and how to go about it?
But when exactly should you start an ADR? Creating a Walking Skeleton is the perfect time for this, since that’s when the team defines the most critical elements of the architecture; this milestone allows the team to navigate the intense development phase leading up to the MVP while minimizing technical debt. Of course, nothing is set in stone: the architecture is meant to evolve alongside the product.
The ADR does exactly that, but it’s important to clarify how: an ADR is immutable. To amend a previous decision, the team doesn’t modify the corresponding ADR—it adds a new one that references the old one. In other words, an “append-only” mechanism—and if you thought of “Event Sourcing,” well done! 👏 Ideally, decisions will be numbered consecutively, as is done with invoices. And all of this will be tracked by a version control tool (commonly Git).
On closer inspection, maintaining an ADR is a practice that really brings a team together, in the sense that acceptance of its operating procedures is tantamount to a charter, while the decisions recorded therein serve as rules. It wouldn’t be unreasonable, in fact, to broaden its scope to include decisions of all kinds related to the team’s life. And this has already been done: I know of at least one instance where it was applied in human resources, with no connection to tech whatsoever.