The Complete Guide to Architecture Decision Records

The most expensive decisions in any technology organisation are the ones nobody wrote down. I don't mean that as a platitude. I mean it quite literally: I once inherited an architecture with over 200 significant decisions — none documented. It took six months of archaeology through old Slack threads, dead Confluence spaces, and interviews with people who'd half-forgotten conversations from two years prior to reconstruct why the system was built the way it was. Six months of senior engineering time, burned, because nobody thought recording decisions was important enough to do properly.

Architecture decisions are the most expensive things that technology organisations routinely fail to track. A single decision — which database engine, whether to go multi-tenant, how to handle authentication across services — can lock in millions of pounds of technical direction for years. And yet in most organisations I've worked with, those decisions live in someone's head, or in meeting minutes that nobody ever reads again, or on a Confluence page that's already out of date by the time it's published.

This guide is for anyone who's felt that pain. Whether you're an architect trying to get your organisation to take decision governance seriously, or a CTO wondering why your teams keep relitigating the same choices, or a governance lead trying to build an audit trail that will actually hold up to scrutiny — this is the practical version. Not the Wikipedia definition. Not the "here's a markdown template" blog post. The real thing.

What an ADR Actually Is

Forget the academic definition for a moment. An architecture decision record is the answer to a question your future self is going to ask: "Why the hell did we do it this way?"

That's it. That's the core of it. An ADR captures an important architectural decision along with enough context that someone encountering the system in six months, two years, or a decade can understand not just what was decided, but why. What was the situation? What options were on the table? What trade-offs did we accept? Who was in the room?

The concept was formalised by Michael Nygard in a 2011 blog post, and the basic structure hasn't changed much since:

Simple enough, right? The problem is never the template. The problem is everything around it.

The MADR Format — What Works, What Doesn't at Scale

The Markdown Any Decision Record (MADR) format is probably the most popular structured ADR template in the wild today. It extends the basic Nygard structure with sections for options considered, pros and cons of each option, and links to related decisions. It lives in your Git repo alongside the code. Developers love it because it fits their workflow.

For a team of five to fifteen engineers working on a single product? MADR is genuinely excellent. Low ceremony, version-controlled, reviewed alongside pull requests. I've used it on smaller projects and it works well.

For anything enterprise-scale, MADR falls apart. And I say this having tried to make it work across a portfolio of 60+ services with multiple teams.

Here's why:

• No approval workflow. A markdown file in a Git repo has the same governance authority as a code comment. Anyone with write access can merge it. There's no formal review gate, no sign-off from an architecture review board, no record of who actually approved the decision versus who just didn't object.
• No cross-cutting visibility. When your ADRs live in individual service repos, nobody has a view of all the decisions across the portfolio. The enterprise architecture team can't see patterns. The CTO can't see risk accumulating. Decisions that conflict with each other across different services go unnoticed.
• No connection to services or principles. An ADR that says "we chose Kafka for event streaming" is useful. An ADR that's explicitly linked to the three services it affects, the EA principle it upholds (or deviates from), and the business case that funded it? That's governance.
• No lifecycle management. Decisions get superseded, deprecated, revisited. In a markdown file, "superseded" means someone remembers to update the status field. In practice, nobody does.

MADR is a fine ADR template. It's not an ADR governance system. Those are very different things.

Why ADRs Fail in Practice

I've seen ADR initiatives fail in every kind of organisation — startups, banks, government departments, SaaS companies. The failure modes are remarkably consistent.

The Confluence graveyard

Someone creates a "Architecture Decisions" space in Confluence. The first few ADRs get written with great enthusiasm. By month three, the space has 40 pages, no consistent structure, and the search is useless. By month six, people have stopped writing new ones because nobody reads them anyway. The decisions keep happening in meetings. The Confluence space becomes a monument to good intentions.

No workflow, just documents

This is the most common failure. Decisions get made in a meeting — a technical design review, a stand-up, a Slack thread that got heated. Somebody says "we should write that up as an ADR." Nobody does. Or somebody does, weeks later, working from memory, missing half the context and all of the dissenting opinions that were actually the most valuable part of the discussion.

No connection to the systems they affect

An ADR that lives in isolation is a historical curiosity. If I can't see which services are affected by a decision, I can't assess the blast radius when I need to revisit it. If I can't see which decisions apply to a service I'm about to modify, I'm flying blind. The decision log and the service catalogue need to talk to each other. In most organisations, they don't — because they're in completely different tools, maintained by completely different people.

No audit trail

Try answering these questions about any decision in your organisation's architecture: Who proposed it? When? Who reviewed it? Who approved it? Were there conditions attached? Were those conditions met? Was it ever revisited?

If you can't answer all of those from your current tooling, you don't have an architecture decision log — you have a collection of notes. And when the auditor asks (and they will, if you're pursuing SOC 2 or ISO 27001), "notes" won't cut it.

The 7-Phase ADR Lifecycle

After years of trying to make lightweight approaches work at scale and watching them buckle, I've landed on a seven-phase lifecycle that balances rigour with pragmatism. This is the model we built into HelixGate's ADR governance, but the pattern works regardless of tooling. Here's what each phase actually means in practice:

Is this more ceremony than a markdown file in a Git repo? Obviously. But the ceremony exists because the alternative — decisions made without scrutiny, approved without record, and forgotten without trace — has a cost that compounds over years. I've lived through that compounding. The interest rate is brutal.

The key thing about this lifecycle is that it's not just a status field with seven values. Each transition is a specific act by a specific person, recorded with a timestamp, and visible to anyone who needs to see it. That's what makes it governance rather than documentation.

Connecting ADRs to the Rest of Governance

Architecture decisions don't exist in a vacuum. Every significant decision touches other things:

• Services. Which services does this decision affect? If I'm deprecating a message broker, every service that depends on it needs to know. The ADR should be explicitly linked to those services in your service catalogue.
• EA Principles. Does this decision uphold or deviate from your enterprise architecture principles? If it deviates, that deviation should be explicitly acknowledged and justified. Principles without enforcement are just suggestions.
• Business Cases. Major architecture changes usually need funding. The ADR should link to the business case that's paying for the work. This creates traceability from investment to implementation — something finance teams and auditors both appreciate.
• Other ADRs. Decisions build on each other. ADR-042 might supersede ADR-019. ADR-055 might depend on the assumption that ADR-042 is still valid. If these links aren't explicit, you end up with a decision history that reads like a choose-your-own-adventure book with the page numbers torn out.

This is where the real power of ADR governance shows up. It's not about making architects fill out forms. It's about creating a connected map of decisions, services, principles, and investments that lets you understand your architecture as a whole rather than as a collection of isolated choices.

Practical Tips for Getting ADR Governance Adopted

I've rolled out ADR processes three times at different organisations. The first time was a disaster. The second was mediocre. The third time I finally got it right. Here's what I learned:

Start with the decisions that are already causing pain. Don't announce a grand new governance initiative. Find the decision that three different teams are currently arguing about because nobody can find the original rationale, and say: "Let's document this one properly. Here's the format." Let the value sell itself.

Make the template shorter than you think it should be. The first ADR template I ever inflicted on an organisation had 14 sections. Nobody filled in more than 5. Cut it to the essentials — context, decision, consequences — and let people add more detail if they want to.

Make the workflow match how people actually work. If your architects live in Jira, don't make them switch to a separate tool just for ADRs. If they're already doing technical design reviews, slot the ADR review into that existing ceremony rather than creating a new meeting.

Show the audit trail to someone who's been burned. Find the tech lead who spent three weeks investigating why a system was built with a particular pattern, only to discover it was an accident that nobody questioned. Show them what an ADR governance trail looks like. They'll become your most passionate advocate.

Don't try to retroactively document everything. You'll burn out. Start from today. Document decisions going forward. Backfill the most critical historical decisions when you have time, but don't let perfect historical coverage block forward progress.

Give ADRs sequential numbers and never reuse them. ADR-042 is ADR-042 forever, even if it gets superseded. This sounds trivial but it eliminates an entire category of confusion. People can reference decisions by number in Slack, in meetings, in other documents. "Per ADR-042" becomes a thing.

When You Need Tooling vs When a Wiki Is Fine

I'm going to be honest here, even though I'm the founder of a company that sells ADR governance tooling.

A wiki is fine when:

• You have fewer than 30 active ADRs
• One team or a small group of architects makes all the decisions
• You don't need formal approval workflows
• You're not subject to compliance audits that require decision traceability
• You don't need to connect decisions to a broader service catalogue or principles framework

If all five of those are true, use a wiki. Use MADR in your Git repo. Use a shared Google Doc. Whatever your team will actually maintain. The best ADR system is the one that gets used.

You need proper tooling when:

• Multiple teams across a portfolio are making architectural decisions
• You need an approval workflow with formal sign-off (ADB, ARB, or equivalent)
• Compliance requires an immutable audit trail of who decided what and when
• You need to link decisions to services, principles, or business cases
• Decision volume means you need search, filtering, and reporting
• You need to track conditions attached to approvals and verify they're met

The inflection point, in my experience, is around 50 active decisions across more than 3 teams, or the moment someone says "we need to prove to an auditor that this decision was properly governed." At that point, a Confluence space or a folder of markdown files stops being adequate and starts being a liability.

Making It Stick

The first ADR I ever wrote was on a napkin during a heated meeting about whether to adopt microservices. It captured the context (monolith was becoming unmanageable), the decision (decompose along domain boundaries starting with billing), and the consequences (team reorganisation required, eventual consistency accepted). That napkin was more useful than the 80-page architecture document that already existed, because it captured the why alongside the what.

Architecture decision records aren't complicated. The template is simple. The concept is straightforward. What's hard is building the organisational muscle to capture decisions consistently, review them properly, connect them to the systems they affect, and maintain an honest record over time.

If you're starting from zero, start small. One template, one decision, one review. Prove the value. Then build the ADR workflow that your organisation actually needs — whether that's a folder in a repo or a full seven-phase governance lifecycle with ARB reviews and immutable audit trails.

The decisions are going to get made either way. The only question is whether anyone will remember why.