On a consulting job, I reviewed a system that a new team was migrating to a different technology.
Note: I’m sharing this story with the client’s permission. At their request, I don’t name them: I’m telling it as an experience, not as a case study.
The first thing I did was read what existed before them. And there was a lot. The previous team had been very good and very organized: ADRs, RFCs, commits with proofs of concept, documented and tested code, Confluence pages with the decisions and even the scribbles from their analysis. Links to the Slack threads and the Jira tickets. You could tell they were thinking about whoever came next.
Then I opened the migration.
In the part I reviewed, I didn’t find the reasons behind the new decisions written down.
The irony is that the old system, the one being replaced, was the one that left the most context for changing it. If the migration shipped like that, whoever came next would find the code, but not those reasons.
As long as the people who made the decisions are still around, you can ask them. And when they’re gone?
You can understand the code and still not know enough to change it.
#.Where did the decision go?
The PR can explain what changed, and it helps a lot when it’s small and tied to a ticket.
The ticket can say what we had to deliver. So why did we rule out the other option?
That’s what Architecture Decision Records, or ADRs, are for: short documents where we write down an important decision, its context and its consequences.
Michael Nygard, who popularized the idea in 2011, put it this way: someone who joins a project and doesn’t understand the reason behind a decision has two choices. Blindly accept it, or blindly change it.
A few weeks ago I wrote about what happens when a team stops talking and everyone talks to their own AI instead: decisions nobody can explain six months later, because they were never discussed. That consulting job got me thinking about what comes next, when on top of that nobody wrote them down, and we trust that we’ll “just ask the AI later.” As if explaining a system were the same as remembering how we got there.
#.What an audit doesn’t guarantee
If your company goes through a SOC 2 audit, you might think this is already covered: change controls leave a trail. SOC 2 is an audit report on a company’s controls, built on the AICPA’s Trust Services Criteria.
One of those criteria, change management (CC8.1), asks, among other things, that changes to software, infrastructure, data and procedures be authorized, documented, tested and approved. That trail doesn’t have to live in the repository. CC8.1 doesn’t require automated tests or a ticket per PR, although a company may have defined them as part of its own controls.
A team can have every change with its ticket, its reviewed PR, its tests and its approval. A recorded approval shows that someone approved the change. Not that anyone knew why.
SOC 2 doesn’t prescribe ADRs. Compliance evidence can hold the reasons too, but meeting the criterion doesn’t guarantee they end up written where the next person to change the system will need them.
#.A convincing explanation is not a reason
An AI can find clues in tickets and commits. If the reasons ended up there, it can help recover them. It can also come up with arguments we hadn’t considered, or recognize that it’s missing information.
The trouble starts when we treat those arguments as the real story of the decision. A queue absorbing traffic spikes doesn’t prove that’s why we chose it.
“Better scalability.” “Looser coupling.” It all sounds right. But were those the reasons? Or did we have three weeks, a legacy integration and nobody available to maintain another service?
And AI can only read what we leave behind. If the why was never written down, AI can suggest one that sounds reasonable. That doesn’t confirm it was the reason.
If we use AI to justify after the fact what we never discussed beforehand, the document can end up better written than the decision it represents.
#.Writing is part of deciding
Martin Fowler says it in his article on ADRs: writing them helps clarify thinking, especially in a group, and brings out the different points of view within the team. When we try to explain a decision, we find out what we didn’t know and where we disagreed.
That’s where AI does help: organizing notes, finding contradictions, telling you what’s missing. But if we leave it to AI to supply the reasons and approve whatever sounds convincing, we skip exactly the part where we decide. It’s the same cognitive surrender I wrote about two weeks ago.
The serious criticism of ADRs has a point: a person can also write down the presentable reason instead of the real one. Writing it doesn’t make it true. That’s why it matters to write it close to the moment of deciding, with the people who decided and with the real constraint, even if it doesn’t look good.
If you have to reconstruct an old decision, ask the people who were there while you can, and make it clear that it’s a reconstruction. Whatever nobody can confirm stays a hypothesis, whether a person or an AI suggested it.
If the why is already clear in a PR or a ticket that’s easy to find, there’s no need to copy it into another document. I’d save ADRs for decisions that affect several parts of the system or that would be expensive to reverse.
An ADR has a cost: someone has to write it, keep it where people will find it, and mark it when another one replaces it. That’s why you don’t need huge documents nobody reads. A short record can be enough. For example:
We process these requests in the background because the provider can take longer than our HTTP request timeout. We didn’t raise that timeout because it would leave connections open while we wait on the provider. We accept that the user gets the result later. We’ll revisit this if the provider offers a fast, reliable synchronous response.
To start, I’d keep three questions:
- What did we decide, and why did we rule out the other option? The real constraint, not the ideal one.
- What did we accept in return?
- When would we revisit it?
#.So we can change our minds
A written decision isn’t an eternal order. It may have been a mistake, or it may have stopped making sense. But if you know why it was made, you can argue about it properly. And when you replace it, Fowler recommends not rewriting the old record, but marking it as superseded and linking it to the new one.
That’s what I found in that old system: a trail of why they made those decisions. With that, changing it didn’t take guesswork.
Think about your team’s last big decision. Where is the why written down?
AI can explain the code to whoever comes next. The why is ours to leave behind.