ADR Templates in the Wild: What Works, What Breaks, and Why Teams Give Up on Them

Your Confluence page says the billing service uses synchronous calls. The ADR from last quarter says it should be async. A Slack thread from two weeks ago confirms the team switched to event-driven. All three are technically “documentation.” None of them agree on reality.

Most teams that adopt Architecture Decision Records hit this exact problem within a year. The format you choose - and how you use it - determines whether your ADRs stay useful or quietly become another source of contradictions.

Decisions have a lifecycle nobody tracks

The problem isn’t that teams don’t write decisions down. It’s that nobody tracks what happens to those decisions after they’re written.

Architecture Decision Records were introduced by Michael Nygard in 2011 as a lightweight way to capture the “why” behind technical choices. The format is brilliant in its simplicity: context, decision, consequences. A few paragraphs. Stored close to the code. Easy to write, easy to read.

Most engineering teams that adopt ADRs go through the same arc. The first dozen feel revelatory. New hires read them and actually understand why the system is shaped the way it is. Senior engineers stop repeating themselves in architecture reviews. For a few months, it works.

Then the problems start.

ADR-014 says “we chose PostgreSQL for the events store because we need ACID guarantees.” ADR-031 says “we’re migrating the events store to Kafka Streams for throughput.” ADR-014 was never updated, marked as superseded, or linked to ADR-031. It still shows up in search. A new engineer reads it, assumes Postgres is the events store, and builds against the wrong database.

The failure isn’t that people stopped writing ADRs. They kept writing them. The failure is that the relationship between ADR-014 and ADR-031, that one replaces the other, exists only in the heads of the people who were in the room when the decision changed. There’s no decision provenance, no traceable chain from the current choice back to the ones it replaced.

ADR templates: what exists and what actually works

Not all ADR formats are equal. The template you choose shapes whether your team actually writes them, whether they stay useful over time, and whether they can model the supersession problem at all. Here are the four most common formats in practice, with honest assessments of where each one breaks down.

Nygard’s original format

This is the one that started it all. Michael Nygard proposed storing short text files alongside the codebase, each one capturing a single decision.

# ADR-014: Use PostgreSQL for the events store

## Status
Accepted

## Context
The events store needs ACID guarantees for billing-related
event processing. We considered DynamoDB for scalability
but cannot accept eventual consistency for financial records.

## Decision
We will use PostgreSQL 15 with partitioned tables for
the events store. Events older than 90 days will be
archived to S3.

## Consequences
- Write throughput is capped at ~5,000 events/sec
  per partition. Acceptable for current load but will
  need revisiting if we exceed 10x growth.
- Team needs PostgreSQL operational expertise.
- Backup and disaster recovery use existing Postgres
  tooling (pg_dump, WAL archiving).

Pros:

• Minimal friction. Four sections, a few paragraphs. An engineer can write one in ten minutes.
• Lives in the repo as a markdown file, alongside the code it governs. Moves through the same review process.
• Low barrier to adoption. The simplest format to introduce to a team that has never written ADRs.

Cons:

• No structured field for “superseded by” or “supersedes.” The status field exists, but nothing enforces updates. When a later decision replaces this one, the original still says “Accepted” unless someone remembers to go back and change it.
• No place to record what alternatives were considered and why they were rejected.
• Teams that grow past 50 or so ADRs start discovering contradictions because the format has no mechanism for linking decisions to each other.

Nygard’s format is the right starting point for any team that doesn’t have ADRs yet. Adoption matters more than structure, and this format maximizes adoption. But plan to outgrow it.

MADR (Markdown Any Decision Records)

MADR extends Nygard’s format with explicit sections for the options you considered and rejected. It was designed by Oliver Kopp and contributors specifically to address the gap in Nygard’s template: the missing “why not the alternatives?”

# Use Kafka Streams for the events store

## Status
Accepted. Supersedes ADR-014.

## Context and Problem Statement
Event throughput has grown 8x since we chose PostgreSQL
for the events store (ADR-014). We're hitting partition
write limits during peak billing cycles and the operations
team is spending 15+ hours/month on manual partition
management.

## Considered Options
1. Vertical scaling of PostgreSQL (larger instances)
2. Kafka Streams with exactly-once semantics
3. Amazon Kinesis Data Streams
4. Stay on PostgreSQL with Citus extension

## Decision Outcome
Chosen option: Kafka Streams with exactly-once semantics.

### Positive Consequences
- Throughput scales horizontally with partition count.
- Event replay is built into the platform.
- Team already operates Kafka for three other services.

### Negative Consequences
- Lose ACID guarantees. Financial reconciliation now
  requires a separate consistency check job.
- Kafka operational complexity is higher than managed
  Postgres.

## Pros and Cons of the Options

### Vertical scaling PostgreSQL
- Good: No migration. No new operational burden.
- Bad: Buys 6-12 months at most. Doesn't solve the
  partition management toil.

### Amazon Kinesis
- Good: Fully managed. Lower ops overhead than Kafka.
- Bad: Vendor lock-in. No exactly-once semantics
  without custom deduplication.

### PostgreSQL with Citus
- Good: Keeps relational model. Horizontal scaling.
- Bad: Citus operational experience is zero on the team.
  Migration path from partitioned tables is unclear.

Pros:

• The “Considered Options” and “Pros and Cons” sections are the most valuable addition to the ADR format since Nygard’s original. A new engineer reading this a year later doesn’t just know what was decided - they know what was rejected and why.
• Prevents the most common re-litigation pattern: someone proposes an alternative that was already evaluated and dismissed.
• Built-in “Supersedes” convention in the status line. A meaningful step toward lifecycle tracking that Nygard’s format lacks entirely.

Cons:

• Longer. The full template with all options documented can run to two pages. For a lot of teams, this is exactly where “we should write ADRs” quietly turns into “we’ll do it later.”
• I’ve seen teams adopt MADR, write five gorgeous records, then quietly stop because each one takes 30 to 45 minutes.
• The “Supersedes ADR-014” line in the status field is just text - a convention, not a link. Nothing stops the original ADR-014 from continuing to look current in search results.

MADR is the best general-purpose ADR template for teams that have outgrown Nygard’s original. If your team is past 20 ADRs and you’ve already had the experience of someone proposing a rejected alternative, MADR solves that problem well.

Y-statements

Y-statements compress an entire decision into a single structured sentence. The format was proposed by Olaf Zimmermann as a way to capture decisions with minimal overhead.

In the context of the events store hitting PostgreSQL
write limits during peak billing,
facing the need to scale event throughput beyond 5,000/sec
without manual partition management,
we decided to migrate to Kafka Streams
and neglected Amazon Kinesis and Citus,
to achieve horizontal scalability with event replay,
accepting that we lose ACID guarantees and need a
separate financial reconciliation job.

That’s the entire record. One sentence. Context, constraint, decision, rejected alternatives, desired outcome, accepted tradeoff.

Pros:

• Near-zero friction. You can write a Y-statement in two minutes.
• Captures 80% of the value in 20% of the time. For teams that won’t write full ADRs because the overhead feels too high, this is often the difference between some record and no record.
• Excellent for decisions that don’t warrant a full page - choices that are too significant to forget but too small to justify a ceremony.

Cons:

• No status field. No supersession mechanism. No place to mark a decision as replaced.
• Thin on reasoning. If someone reads this 18 months from now and wants to understand why Kinesis was rejected, “neglected Amazon Kinesis” doesn’t give them much to work with.
• Resists updates. When the decision changes, teams are more likely to write a new Y-statement than to find and update the old one, which brings you back to the contradiction problem.

Y-statements are best used as a complement to a more structured format. Use them for the smaller decisions that would otherwise go unrecorded entirely. But for significant architectural choices, use MADR or a similar template that can model the full reasoning and lifecycle.

The Alexandrian pattern

Named after architect Christopher Alexander, whose pattern language inspired the approach. This format frames every decision as a tension between competing forces, resolved by a specific choice.

# Events Store Migration to Kafka Streams

## Prologue
The billing system processes financial events that
require reliable, ordered delivery. The original
events store (PostgreSQL) served this well at low
volume but has become an operational bottleneck.

## Context
Peak billing cycles generate 40,000+ events/sec.
PostgreSQL partitioned tables cap at ~5,000/sec per
partition. The operations team spends 15 hours/month
on manual partition management. Two incidents in Q3
were caused by partition exhaustion during flash sales.

## Forces
- **Reliability**: Financial events cannot be dropped
  or duplicated. The business requires exactly-once
  processing semantics.
- **Throughput**: Current architecture cannot handle
  projected 10x growth without constant manual
  intervention.
- **Operational cost**: The team already operates Kafka
  for three services. Adding a new data platform (Kinesis,
  Citus) increases operational surface area.
- **Consistency**: ACID guarantees simplify reconciliation.
  Losing them introduces a new class of operational work.

## Solution
Migrate the events store to Kafka Streams with
exactly-once semantics enabled. Build a separate
reconciliation job to verify financial consistency
daily. Retain PostgreSQL as a read-optimized
projection for billing queries.

## Consequences
Throughput scales horizontally. Event replay is native.
But the team now owns a consistency verification system
that didn't exist before, and on-call engineers need to
understand both Kafka and PostgreSQL failure modes.

Pros:

• The “Forces” section is what sets this format apart. It names the tensions explicitly, making the reasoning legible even to someone with no prior context.
• Most resilient to the “does this still apply?” question. When forces change (throughput requirements drop, the team loses Kafka expertise), it’s immediately clear which forces drove the original decision and whether the rationale still holds.
• Produces the best long-term documentation. Five years from now, an engineer reading this can reconstruct not just what was decided but the full landscape of constraints at the time.

Cons:

• The heaviest format on this list. Writing a good Alexandrian ADR takes an hour or more, and it requires the kind of careful thinking about forces that most engineers don’t have bandwidth for on a Tuesday afternoon.
• Most teams won’t sustain this level of effort for every decision. Realistic only for the handful of high-stakes choices per year.
• Lacks an explicit supersession mechanism, same as Y-statements and Nygard’s original.

The Alexandrian format is best reserved for high-stakes, hard-to-reverse decisions: database migrations, API contract changes, authentication architecture. For these, the investment in articulating forces pays off over years. For routine decisions, it’s overkill.

Which format to use when

There is no single best template. Anyone who tells you there is probably hasn’t maintained ADRs for more than a year. The most effective teams I’ve talked to use a tiered approach:

• Y-statements for small, reversible decisions that need a record but not a ceremony. “We chose library X over library Y for date parsing because of timezone support.”
• MADR as the default for most architectural decisions. The considered-options section alone justifies the template.
• Alexandrian for the five to ten decisions per year that are genuinely high-stakes. Database choices, API versioning strategy, authentication architecture, data residency. Decisions where the reasoning needs to survive multiple team turnovers.

The template matters less than two things: that the team actually writes records consistently, and that every record has a mechanism for expressing relationship to other decisions.

Why this gets worse, not better

Every team accumulates decisions faster than it can audit them.

If a team of eight engineers making three architectural choices a week produces 150 decisions a year then in two years, that’s 300 decisions. Many of them partially or fully contradict earlier ones.

The paradox is the more disciplined your team is about recording decisions, the bigger this problem gets. More discipline just means more decisions to contradict each other. And it becomes harder, not easier, to know which ones still hold.

Wiki tools actively make this worse. They treat every document as current until someone manually says otherwise.

• Confluence doesn’t know your January architecture page was invalidated by a March Slack thread.
• Notion doesn’t know the design doc in your team’s workspace contradicts the one in the platform team’s workspace.
• Google Docs doesn’t know the proposal it contains was rejected two sprints ago.

These tools store documents. They don’t model the relationships between them.

The result: a growing set of documents that all look equally valid but aren’t. And the people best positioned to resolve the contradictions? Those are the same senior engineers you’re trying to free from being human knowledge retrieval systems.

The breaking point hits around 40 to 60 engineers. Before that, contradictions get caught informally. Someone mentions the old approach in a PR review, someone else corrects them, the team moves on.

Past that point, knowledge silos form. The teams that made Decision A and Decision B might not even share a Slack channel. The contradiction persists silently until it causes an incident or a wasted sprint.

The real problem: decisions live in multiple places

ADRs are one artifact. But architectural decisions get expressed everywhere, creating knowledge silos that no single tool can bridge:

• Confluence pages
• Notion docs
• Jira ticket comments
• Slack threads
• Google Docs
• PR descriptions
• Meeting recordings

The same decision might be partially captured in five different tools by five different people using five different levels of detail.

Now imagine Decision B supersedes Decision A. To keep things clean, you’d need to find every place Decision A was expressed and update or annotate it.

Nobody does this. Nobody can. Not because people are lazy, but because the job is literally impossible to do by hand at scale.

This is documentation fragmentation at its most dangerous. Documents don’t just go stale - decisions actively replace other decisions, and nothing tracks that replacement. Without that chain of decision provenance, your documentation becomes a graveyard of half-truths.

Here’s how it plays out in practice. An on-call engineer searches for “retry logic billing service.” Three results come back:

1. An ADR from 2024 recommending exponential backoff
2. A Confluence runbook describing fixed-interval retries
3. A design doc proposing circuit breakers

Which one reflects reality?

The engineer doesn’t know. Can’t know from the documents alone. So they page the senior engineer who built the system, and now you’re doing ADR archaeology over Slack at 2am. Tribal knowledge with extra steps.

What actually helps

You won’t solve this with better writing discipline. The problem is structural, not behavioral. But there are practices that reduce the damage.

Give every decision a status field and enforce it. ADR templates often include a status (proposed, accepted, deprecated, superseded). Most teams fill this in once and never update it. Make status reviews part of your quarterly planning: for each domain, walk through active ADRs and ask “does this still hold?” It’s boring, but this one change alone will save you from a surprising number of “wait, which version is real?” moments. Keep the ritual lightweight. If it feels like an audit, people will skip it.

Link superseding decisions to what they replace. When ADR-031 replaces ADR-014, say so explicitly in ADR-031. Include a line: “Supersedes ADR-014.” And update ADR-014’s status to “Superseded by ADR-031.” This takes thirty seconds and creates decision provenance: a traceable chain of reasoning over time. Some teams automate this with templates that include a “supersedes” field. The mechanism matters less than the habit.

Reduce the surface area of decisions. If your decisions live in seven tools, documentation fragmentation is inevitable because no human can track relationships across seven information surfaces. Pick one canonical location for architectural decisions and enforce it, even if context and discussion happen elsewhere. The decision itself, the final “here is what we chose and why,” should have exactly one home. Everything else is commentary.

Treat contradictions as incidents, not housekeeping. When someone discovers that two documents say conflicting things about the same system, that’s a knowledge reliability failure. It means someone, somewhere, is building on wrong assumptions. Track these the way you’d track a bug: who found it, what was contradicted, what was the resolution, how do we prevent it. Teams that treat contradictions as routine background noise end up with documentation nobody trusts.

The compounding contradiction

Every untracked supersession is a small bet. The bet: nobody will rely on the outdated version.

Early on, that bet pays off. The team is small. People remember. Contradictions get caught in code review.

But the bets compound.

• Year one: 50 untracked supersessions.
• Year two: 150.
• Year three: You’ve stopped counting.

Each one is a potential wrong assumption. A wasted sprint. An incident that takes three hours instead of ten minutes.

And unlike code bugs, these failures are sneaky. Nothing screams at you. The engineer who builds against the wrong ADR doesn’t get a test failure. They get a working system that does the wrong thing. Everything looks fine until it collides with something else weeks later.

If your team writes ADRs and your engineers still regularly ask “wait, is this still how we do it?”, the problem isn’t adoption.

It’s that your ADRs don’t model the one relationship that matters most: which decision replaced which, and when.

Start with one change. Add a “Supersedes” field to your template. Then ask how many of your existing records would need one.

---

You can script around parts of this, but at some point you’re fighting your tools. Templates and discipline get you far, but they can’t track relationships across Confluence, Slack, Google Docs, and ADRs all at once. That’s the problem we’re working on with Nexalink - connecting your existing knowledge sources so your team finds the current answer, not the loudest one. See how it works.