ADR

ADR — Architecture Decision Record.

I keep running into engineering teams that underestimate ADRs.

When ADRs are imposed from above, every entry turns into a long-winded story that you can’t actually read through to understand what motivated a given decision. ADRs like that get written “for the sake of having them,” for approval from coworkers and management. The mistaken assumption is that the “effort” poured into a long (and often incoherent) narrative is somehow valuable to the team.

These ADRs get written once, are never read by anyone, and are kept around “because they’re an important document.”

The main job of an ADR is to convey to colleagues, including future ones, the context of a decision.

Don’t turn an ADR into a long story. State the situation clearly, list the reasons that drove your decision in bullet form, capture the expected consequences, what your choice might affect later, what it might constrain you with, and how those constraints can be worked around or lifted.

An ADR isn’t truth carved in stone. Over time, or once it becomes clear that the decision is outdated and no longer meets new requirements, it should be revisited: the current record gets rejected and replaced with a new one.

Another common problem with ADRs is judging the significance of a decision. Developers feel like they’re describing yet another small detail that everyone already knows. In practice, no. Context is forgotten the moment the next meeting wraps up.

Here’s an example of an ADR that was mistakenly considered irrelevant. The team was asked to capture cluster naming rules. The thinking was that this is a trivial thing that doesn’t affect development. Why write an ADR for it?

As the work progressed, it turned out that:

• Validation rules diverged between the application’s frontend and backend;
• Cluster names feed into the hostnames of the machines in the cluster;
• Using the cluster name as part of the hostname imposes a set of constraints on user input.

What’s worth capturing in an ADR in this case?

• The fact that constraints are placed on the cluster name;
• The reasons those constraints are being introduced right now;
• The validation rules as a single source of truth for frontend and backend developers;
• The consequences of the decision, e.g. possible constraints when importing data from external systems.

The engineering culture of my colleagues is top-tier. We consistently capture and follow through on the decisions we make. The ADRs we write don’t run longer than one screen of a 13" laptop, always describe the problem and the context of the decision, answer the “why,” and head off potential negative consequences. Outdated ADRs are revisited and replaced with new ones aligned with current requirements.