Architecture Decision Records Are a Compounding Asset

The most underrated compounding asset in a portfolio is a written record of why you decided things. Not what you built, why. An architecture decision record, or ADR, is a short note capturing a choice, the options you weighed, and the reason you picked one. It costs ten minutes to write and it saves you from re-litigating the same decision every time it comes up in a new product. Across twenty apps, the same architectural questions recur constantly. Answering each one once, in writing, is the difference between a foundation that accumulates judgment and one that forgets it.

I keep ADRs for every load-bearing choice in the shared stack. Not because I love documentation, but because I am the only one who remembers why anything is the way it is, and my memory is not a reliable place to store the reasoning behind a portfolio.

Why the reason matters more than the decision

Code tells you what the system does. It never tells you why. Six months later you look at a choice, cannot remember the reasoning, and either leave it alone out of fear or change it and rediscover the reason the hard way, in production. Both are expensive. An ADR closes that gap. It preserves the context that the code cannot carry.

This matters most in a shared foundation, because foundation decisions echo into every consumer. When I decided how versioning the shared foundation would work, that choice shaped every app downstream. If I forget why I chose it, I risk breaking the reasoning the next time I touch it. The ADR is what lets me change the foundation later without stepping on a constraint I set for a good reason I no longer remember.

What an ADR actually contains

Keep them short. An ADR that takes an hour to write will not get written. Four parts is enough.

• The decision. One sentence. "We pin foundation versions per app rather than tracking latest."
• The context. What forced the choice. What problem, what constraints, what was true at the time.
• The alternatives. What else you considered and why you rejected it. This is the part future-you will thank you for, because it stops you re-evaluating options you already ruled out.
• The consequences. What this choice makes easy and what it makes hard. Every decision has a cost. Name it so nobody is surprised later.

That is it. No template ceremony. The value is in capturing the reasoning while it is fresh, not in the formatting.

ADRs are how knowledge outlives the person

In a solo portfolio, the biggest risk to knowledge is me forgetting. In a team, it is people leaving. Either way, undocumented reasoning is knowledge with a bus factor of one. ADRs raise that number. They move the reasoning out of a head and into the foundation, where a new hire, or an AI agent, can read it and understand not just how the system works but why it works that way.

This is the same principle behind playbooks compounding faster than code, pointed at decisions instead of procedures. A playbook says how to run a job. An ADR says why the system is shaped the way it is. Together they turn tacit knowledge into an asset the portfolio owns, not one you rent from your own memory.

Where ADRs stop you from repeating mistakes

The real payoff shows up when a decision comes back around. You are about to build a new product. A question arises that you swear you have answered before. Without ADRs, you argue it again from scratch, maybe reach a different conclusion, and now two products handle the same thing two ways for no reason. With ADRs, you find the record, read why you chose what you chose, and either follow it or consciously override it because the context changed.

That is how a foundation accumulates judgment instead of resetting it. It is the difference between the paved road having a reason behind every stone and the paved road being a pile of choices nobody can defend. When someone asks why the foundation works this way, "there is an ADR for that" is a much better answer than "I think there was a reason."

Start with the decisions you will forget

You do not need to document every choice. Document the ones that were hard, the ones with real tradeoffs, and the ones that shape things downstream. If a decision was obvious, skip it. If you argued with yourself for an afternoon, write it down, because you will argue with yourself again in a year unless you do.

I keep ADRs in the same project memory the build platform reads at Bootspring, so when an agent works on the foundation it can see not just the code but the reasoning behind it. The decisions you make today are worth more if you can remember why you made them. Write the reason down while it is fresh. It is the cheapest compounding you will ever buy.