ADRs: memory for humans and context for agents

A few years ago, during my time at Santander Bank, we started using Architecture Decision Records (ADRs) to keep track of certain architectural decisions: what had been decided, which alternatives had been considered and, above all, the context in which that decision was made.

I have to admit that at first I found them quite tedious. When you are deep in the day-to-day work of a project, many of those reasons seem obvious, and documenting them feels like extra work, especially when the squads are not particularly large. There is a strange feeling of explaining to the future something that everybody knows today.

Over time, however, I started to appreciate their usefulness much more.

Teams change, people leave and context fades far more quickly than we tend to think. Decisions that look strange, unnecessarily complex or simply bad months or years later often made quite a lot of sense under the constraints, information and deadlines that existed at the time.

And obviously, git history is not always the best place to reconstruct all of that :P

Code can show what changed and, if you are lucky, who changed it. But it rarely explains properly why another technology was rejected, why two domains were deliberately separated or what problem sat behind a solution that now looks over-engineered.

What I began to like most was that ADRs were especially valuable for bad decisions too. Not to justify them or to say “it was the right choice at the time”, but to understand them. There is an important difference between inheriting an absurd decision and discovering that it was a reasonable bet that went wrong, or one that stopped making sense when the context changed.

Recently I have been thinking about this again because of spec-driven development (SDD) and all this craziness around building software with more and more agents involved.

Specs can capture much more than simply what we want to build. They can describe behaviours, constraints, edge cases, acceptance criteria and even some of the intent behind a change. But I think there is still a risk: as we delegate more of the implementation, we may lose part of the story of why the system gradually took a particular shape.

Because behind an architecture there are decisions that outlive many specs. Technologies that were evaluated and rejected. Boundaries that were established deliberately. Technical debt that was accepted in the full knowledge that it was debt. Solutions that were already tried and did not work. Even decisions that came out of a difficult conversation, a major incident or a night when something broke and somebody had to fix it.

All of that is part of the system, even when it does not appear in the code.

That is why I think ADRs can take on a new role in these workflows. Not only as a historical record for people, but as part of the context used by agents as well. A kind of shared architectural memory that explains not just how the system works, but why we wanted it to work that way.

One way of doing this could be for the agent to identify the ADRs relevant to that part of the system before implementing a change. If the new implementation conflicts with one of them, the process should force us to stop and review whether that decision still makes sense. And if the conditions have changed, we should record a new decision that supersedes the previous one, instead of silently eroding it one change at a time.

But an ADR on its own should not become a false guarantee either. It can provide context and define boundaries, while tests, policies and continuous integration are what actually enforce them. The spec defines the intent, the ADR preserves the reasoning and the validation tools prevent us from moving outside those guardrails without noticing.

In this way, an ADR stops being only a memory of why we made a decision. It also becomes a bridge between that decision and the boundaries within which we want humans and agents to keep evolving the system.

I suppose there is something quite human in all of this. We build systems over many years and, almost without noticing, we leave part of our doubts, our successes and also our mistakes inside them. When the context disappears, only the outcome remains, and sometimes judging the outcome without knowing the journey is far too easy.

The easier it becomes to generate and modify software, the more important I think it will be to preserve not just the code and the specifications, but also the reasoning that brought the system to where it is today.

Perhaps ADRs were always memory. The difference is that now people are not the only ones who need to be able to read it.