In Poland there is a classic line a repairman says when looking at someone else’s work: “who broke this for you?” I hear a version of it very often when a team takes over an existing system. Someone opens the code and the diagrams, and the verdict is that everything is pointless.
Why does that happen? In my view the reason is simple. Architecture, the design of the system, answers the question of how it should work. Very rarely do we record why it should work that way. Without the why, every decision that no longer fits looks like a mistake.
The previous articles in this series were about the organization around a system: Conway’s Law and the temporary project organization of client and vendor, walking that organization more than once, and mapping who is informed, consulted and accountable. This one is about time. Organizations change, and architecture has to survive those changes without losing the reasons behind it.
Water rarely freezes
There is a well-known line usually attributed to Edward V. Berard: walking on water and developing software from a specification are both easy, if both are frozen (Berard, via Quotewise).
Requirements behave the same way. When they freeze and become rigid, designing a system is relatively simple, and it should work. In real organizations they almost never freeze. The world changes, the business changes, the board changes.
Our industry has noticed. Neal Ford, Rebecca Parsons, Patrick Kua and Pramod Sadalage define an evolutionary architecture as one that supports guided, incremental change across multiple dimensions. The guidance comes from fitness functions: mechanisms such as metrics and tests that give an objective assessment of the architectural characteristics you want to protect as the system changes (Building Evolutionary Architectures, 2nd ed., pp. 5 and 14). Systems thinking, promoted among architects by Diana Montalion in Learning Systems Thinking, comes at the same problem from the side of reasoning about the whole system around the software.
The shared assumption is simple: architecture is continuous work. We have to keep discovering changes and adapting the architecture to them.
Stressors: the park that was dug up
The concept closest to me here is Barry O’Reilly’s residuality theory. You start with a naive architecture that solves the functional problem, then stress it with possible changes in its environment. Those stressors reveal the few states the business tends to fall into, and the architecture is reworked so that it survives in them (Linders, InfoQ, 2025; O’Reilly, Residues, 2025).
I like to explain stressors with a park. Imagine you look at beautiful photos of Planty, a park in Białystok, and when you get there it turns out to be levelled. It happens: in a presentation I once showed a park that had been beautifully kept, with lush plants, until it was completely renovated, trees cut down, lawns and flower beds destroyed. The picture you planned with no longer matches the place.
Organizations have their own earthquakes. A change of the board. A reorganization of one department. Each of them changes the communication paths, and by Conway’s Law, which was the subject of the first article, a change in communication paths puts new pressure on the architecture. The system you designed for one organization is suddenly running in another.
Why the code cannot tell you why
In 1985 Peter Naur argued that a program is more than its source code. It is a theory held in the heads of the people who build it, and that theory cannot be fully captured in code or documentation. When the team that holds it dissolves, the program can keep running while nobody can modify it intelligently any more (Naur, 1985).
That is the “who broke this?” moment, seen from the other side. The new team has the code. It does not have the theory.
Michael Nygard described the consequence for architecture decisions in 2011. A newcomer who does not know the motivation behind a decision has two options: accept it blindly, even when the original reasons no longer apply, or change it blindly and risk breaking something it was protecting. Both are bad (Nygard, 2011).
What gets lost is what I would call the mental model of the architecture and the mental model of the organization. A decision may have been right because that is how the business worked at the time. Or because that is how we understood the business then. Or because that was our level of knowledge. Any of these can matter, and none of them is visible in a diagram.
ADRs: the smallest useful record of why
That is why I care about documenting architecture decisions as Architecture Decision Records.
Nygard’s proposal is deliberately small: a short document per architecturally significant decision, kept with the code, with a title, the context (the forces at play), the decision itself, a status, and the consequences, positive and negative. When a decision is reversed, the old record stays and is marked as superseded, so later readers can see how the thinking changed (Nygard, 2011). The ThoughtWorks Technology Radar moved lightweight ADRs to “Adopt” in 2017, recommending source control over a wiki so the records stay in sync with the code (ThoughtWorks). The ADR community site keeps templates and tooling (adr.github.io).
The section that answers “who broke this?” is the context. Andrew Harmel-Law describes it as the facts surrounding the decision as they were known to the deciders at the time, and notes that readers can also see what the deciders were not thinking about, from its absence (Facilitating Software Architecture, p. 120).
That is where the organization belongs. Technical forces such as load, latency or team skills are the obvious content of a context section. I would add the organizational ones too: who owned the data, which department was accountable, what the business process looked like when we decided.
An illustrative ADR
The example below is hypothetical. It does not come from any project. It builds on the typical data ownership scenario from the previous article.
ADR 12: Customer master data is owned by the billing context
Status: Accepted
Context: Finance and operations both claim ownership of customer data. Finance issues invoices and needs legally valid customer records. Operations is in daily contact with customers and changes contact details most often. The steering group named finance as accountable for customer data. Operations has no budget for maintaining it.
Decision: The billing context owns customer master data. Operations reads it and requests changes through a defined interface.
Consequences: Contact changes from operations reach billing with a delay. If accountability for customer data moves to operations, for example after a reorganization, this decision should be revisited.
The last sentence is the important one. It names the organizational stressor that would make the decision wrong. A team inheriting this system three years later does not have to guess whether the architecture is broken. It can check whether the organization still looks like the one in the context.
Choosing words for different people
Documenting the why is half of the work. The other half is explaining it to people who were not in the room.
We have to choose our words and arguments carefully for each person we talk to in the organization, to defend our decisions, to justify them, and to show why we chose this architecture or this pattern and not another. Montalion gives a useful structure for that: write down the recommendation, add three to five reasons that support it, including a direct connection to the system’s purpose, strengthen them with others, and describe the known negative consequences and valid disagreements, especially the unpopular ones (Learning Systems Thinking, p. 115). That is very close to an ADR, written for people instead of for the repository.
As I see it, architecture is more than drawing diagrams and showing what the system will look like. It is the whole surrounding work: building the mental model, mapping the stakeholders and the organization, justifying decisions, and reacting to the stressors that come from outside.
What this means for the client
For a decision-maker on the client side, this has a very practical side. Teams change. Vendors change. Your own people move on. Each time, Naur’s theory of the system walks out of the door with them.
A few things are worth asking for:
- A decision log from the start. ADRs in the repository, readable by your own technical people, not only by the vendor.
- Organizational context in the records. Which department owned what, who was accountable, what the business process was at the time.
- A review after organizational change. After a board change or a reorganization, go through the ADRs whose context no longer holds.
If you ever take over a system and hear “who broke this?”, the first question to ask back is: do we know why it was built this way?
The last article in the series is about the other half of that work: how an architect earns influence without formal authority and convinces people to follow decisions, based on my conversation with Karol Wiszowaty.
Sources
- Edward V. Berard, attributed quote, “Walking on water and developing software from a specification are easy if both are frozen”, Quotewise.
- Neal Ford, Rebecca Parsons, Patrick Kua, Pramod Sadalage, Building Evolutionary Architectures, 2nd edition, chapters 1 and 2, pp. 5 and 14.
- Diana Montalion, Learning Systems Thinking, chapter 7, p. 115.
- Ben Linders, “Producing a Better Software Architecture with Residuality Theory”, InfoQ, 2025.
- Barry M. O’Reilly, Residues: Time, Change, and Uncertainty in Software Architecture, 2025.
- Peter Naur, “Programming as Theory Building”, 1985.
- Michael Nygard, “Documenting Architecture Decisions”, Cognitect, 2011.
- ThoughtWorks Technology Radar, “Lightweight Architecture Decision Records”.
- Architectural Decision Records, adr.github.io.
- Andrew Harmel-Law, Facilitating Software Architecture, chapter 6 “Architectural Decision Records”, p. 120.
- Case material: Piotr Filipowicz, Walking Talking vlog episode on requirement volatility and walking the organization, own experience as solution architect at Arpeggia.