You know that feeling when you join a new team and realize everything in their codebase was decided by the three people who worked here two years ago, none of whom are still around? You’re reading through migration scripts, database schemas, error-handling patterns — some of it brilliant, some of it baffling — and nobody ever wrote down why any of it exists. The kind of project where the answer to “why is this here” is usually a shrug followed by someone saying, I bet Mark thought we needed it for the v2 launch.

That’s not an edge case. It’s how most software gets built. Decisions get made in hallway conversations, Slack threads that bury themselves under newer messages, whiteboard photos that live on the fridge and are eventually covered up with a calendar. The work ships. The code works. And six months later, when the person who made every decision has left for a better-compensated job at a competitor, nobody outside the code repository actually knows why it was built the way it was.

Enter Architecture Decision Records — or ADRs. The concept is embarrassingly simple. An ADR is a markdown file that says: here’s what we were trying to do, here’s what we chose to do about it, and here’s what I expect will happen because of that choice. Michael Nygard first described them in 2011 in what became the paper “Documenting Architecture Decisions.” The format was basically a short title, a paragraph of context, a stated decision, and a list of consequences — both the good ones the team expected and the trade-offs they were knowingly accepting. It didn’t catch on right away. It spread through engineering teams at places like ThoughtWorks and Heroku in the mid-2010s, then diffused quietly the way the best ideas do: through GitHub repos and blog posts and conference talks that people forwarded to each other with a note saying “every team should be doing something like this.”

The reason the format works when other documentation dies on the page has nothing to do with its structure. ADRs succeed because they force authors to write down what they expect, not just what they decided. Most decisions in software are expressed as commands — use Rust instead of Node, put Postgres behind a caching layer, don’t support IE anymore. Those statements encode a preference but rarely encode confidence. An ADR flips that by asking the author to write out consequences: here’s why I think this will work, and here’s what I think might go wrong. That last part — admitting the risks — is what turns a decision from an announcement into a hypothesis. Hypotheses can be tested. Hypotheses can be revisited when new evidence shows up. ADRs don’t capture decisions so much as they make those decisions legible enough that someone else could reasonably argue with them later, which is exactly the point of documentation that doesn’t just sit there waiting to become irrelevant.

They don’t work everywhere, and frankly I think they fail more often than they succeed when teams treat them as a compliance exercise. The worst ADRs I’ve seen are written by people who need to check a box before shipping code — one paragraph each of mostly interchangeable flavor text about “stakeholder input” and “technical evaluation,” written fast, read never. Every minor change gets an ADR and suddenly you have three hundred documents nobody opens unless a production incident forces them to. The teams that do this right treat ADRs like footnotes in a research paper: important when the question needs an answer, otherwise irrelevant. They keep maybe a dozen or so active, flag old ones when they’re no longer true, and let the best ones collect citations over years instead of just being archived next to the last sprint planning spreadsheet.

The thing I find most useful about ADRs isn’t that they capture decisions at all — teams are going to make decisions with or without documentation. It’s that a well-written ADR makes disagreements visible before they become production fires. When someone writes down their consequences honestly, you can see where the team actually agreed and where they just stopped talking about it. You can read an ADR from two years ago and tell whether the original assumption held up or quietly collapsed while everyone was busy shipping features. That’s not documentation in the traditional sense. It’s a mechanism for collective sense-making that happens to live in a markdown file with a .md extension, because apparently that’s enough structure for people to treat their assumptions seriously.