The Engineering Manager's Guide to Architecture Decision Records

You are debugging a production issue at 3 PM on a Thursday. The service that handles payment processing is timing out. You dig into the code and discover that instead of calling the billing API directly, it publishes messages to a queue, which another service consumes asynchronously. You have no idea why. The direct API call would be simpler, more debuggable, and would not have the failure mode you are currently investigating. You check the wiki. Nothing relevant. You search Confluence. A few stale pages about "messaging infrastructure" that were last updated two years ago. You ask in Slack. Someone replies: "Oh, that was before your time. I think Jake decided that when we were having scaling issues." Jake left 18 months ago. Nobody else remembers the details. You spend the next three hours reading code, tracing message flows, and piecing together enough architectural understanding to fix the bug. The fix itself takes 12 minutes.

An Architecture Decision Record would have given you the answer in two minutes. It would have told you that in March 2023, the team evaluated direct API calls versus message queues for payment processing. It would have explained that under peak load, the billing API was returning 429 errors and dropping transactions. It would have listed the alternatives considered: retry logic with exponential backoff, a circuit breaker pattern, or an asynchronous queue. It would have explained why the queue won: guaranteed delivery, natural backpressure, and the ability to replay failed messages. And it would have noted the tradeoff: increased debugging complexity for asynchronous flows. You would have read it, understood the context, and known exactly where to look for the timeout issue.

This is not a hypothetical scenario. Some version of this plays out on engineering teams every single week. Decisions are made, context is lost, and future engineers pay the price. Architecture Decision Records are the simplest, most effective tool for solving this problem. And yet most teams do not use them.

What Is an Architecture Decision Record?

An Architecture Decision Record, or ADR, is a short document that captures a single architecture decision. Not a design document. Not a spec. Not an RFC. A focused, concise record of one decision: what was decided, why it was decided, what alternatives were considered, and what the expected consequences are.

Michael Nygard popularized the format in a 2011 blog post that proposed storing lightweight decision records alongside code. The idea was deceptively simple: instead of trying to maintain a comprehensive architecture document (which inevitably becomes outdated), capture decisions as a sequence of immutable records. Each ADR is a snapshot of a moment in time. You never edit an existing ADR. If a decision is reversed or superseded, you write a new ADR that references the old one. This append-only approach means ADRs do not suffer from the staleness problem that plagues wikis and design documents.

The key characteristics of a good ADR are brevity, specificity, and immutability. A single ADR should be readable in under three minutes. It should address exactly one decision. And once written, it should never be modified. These constraints are what make ADRs sustainable. They are small enough that people will actually write them, specific enough to be useful, and immutable enough to remain trustworthy over time.

Why ADRs Matter More Than You Think

If you have been an engineering manager for more than a year, you have almost certainly experienced the cost of missing architectural context. ADRs address three problems that compound over time.

They Prevent Re-litigation of Settled Debates

Every engineering team has that conversation. The one that happens every six months when someone new joins, looks at a technical choice, and asks: "Why did we choose X over Y?" Without an ADR, this triggers a meeting. People who were involved try to remember the reasoning. Others who were not involved have opinions about what the decision should have been. The team spends an hour or two relitigating a debate that was already settled. Sometimes the outcome is the same. Sometimes the team reverses the decision without fully understanding why it was made in the first place, only to rediscover the original reasoning six months later.

With an ADR, the conversation is different. "Why did we choose X over Y?" becomes "Here is ADR-023, which explains the decision and the context. Has anything changed since then that would warrant revisiting it?" This is a five-minute conversation, not a two-hour meeting.

They Accelerate Onboarding

When a new engineer joins your team, how long does it take them to understand not just what the system does, but why it is built the way it is? For most teams, this takes months. New engineers learn architectural context through osmosis: overhearing conversations, asking questions in code reviews, and stumbling into historical decisions during debugging sessions.

A well-maintained ADR log compresses this process dramatically. A new engineer can read through 20 to 30 ADRs in a few hours and walk away with a deep understanding of the architectural history. They will know which databases were evaluated and why the team chose the current one. They will understand why certain services communicate synchronously while others use queues. They will see which patterns were tried and abandoned, and why. This is the kind of context that normally takes months to accumulate through tribal knowledge.

They Improve Decision Quality

Writing forces clarity. When you sit down to write an ADR, you have to articulate the problem clearly, enumerate the alternatives you considered, and explain why your chosen approach is better than the others. This process often reveals gaps in reasoning. If you cannot explain why you chose PostgreSQL over DynamoDB in a few paragraphs, the decision probably needs more thought. The act of writing the ADR becomes part of the decision-making process itself, not just a record of it.

This effect compounds across the team. When engineers know that decisions will be documented and visible, they tend to think more carefully about their choices. The ADR becomes a lightweight accountability mechanism that raises the bar for architectural thinking without adding heavy process.

The Anatomy of a Good ADR

A good ADR template is simple enough that people will actually use it, yet structured enough to capture the information that matters. Here is a practical template that has worked well for teams of all sizes.

Title

Use a short, descriptive title with a sequential number. The title should communicate the decision at a glance. For example: "ADR-007: Use PostgreSQL instead of MongoDB for user data" or "ADR-012: Adopt event sourcing for the order management domain." Avoid vague titles like "Database decision" or "Architecture update." The title should tell a reader whether this ADR is relevant to their question without having to open it.

Status

Every ADR has a status: Proposed, Accepted, Deprecated, or Superseded. Most ADRs will be written and immediately marked as Accepted. The Proposed status is useful for decisions that require broader input before being finalized. Deprecated means the decision is no longer relevant (perhaps the feature was removed). Superseded means a newer ADR has replaced this one, and you should include a link to the superseding ADR.

Context

This is arguably the most important section. Describe the situation that motivates this decision. What forces are at play? What constraints exist? What problem are you trying to solve? Be specific. Instead of "We need a better database," write: "Our current MongoDB instance is handling 50,000 writes per second for user profile data. We are seeing increasing query latency for relational queries (finding users by organization, filtering by role and join date) because MongoDB requires application-level joins. Our team has strong SQL experience but limited MongoDB aggregation pipeline expertise."

Decision

State the decision clearly and concisely. "We will migrate user profile data from MongoDB to PostgreSQL 15, using a phased migration with dual-writes during the transition period." One to three sentences is usually sufficient. The context section explains the why. This section states the what.

Alternatives Considered

List the other options you evaluated, with a brief explanation of why each was not chosen. This section is critical because it answers the question future engineers will inevitably ask: "Did they consider X?" For each alternative, include what was appealing about it and why it ultimately did not win.

• Keep MongoDB and optimize queries. We evaluated this but determined that the relational query patterns we need are fundamentally at odds with the document model. Denormalization would help reads but make writes significantly more complex.
• Migrate to CockroachDB. Offers PostgreSQL compatibility with horizontal scaling. However, the operational complexity and cost are not justified at our current scale (500K users), and our team has no CockroachDB experience.
• Use a hybrid approach with MongoDB and a read-replica in PostgreSQL. Adds significant infrastructure complexity for a dataset that fits comfortably in a single PostgreSQL instance.

Consequences

Be honest about what becomes easier and what becomes harder. Every architectural decision involves tradeoffs. Documenting them explicitly helps future engineers understand the boundaries of the decision and when it might need to be revisited.

• What becomes easier: Relational queries, reporting, team familiarity, tooling ecosystem.
• What becomes harder: Schema migrations require more planning. Flexible/schemaless data patterns will need a JSONB column or a separate store. Horizontal write scaling will require sharding or a different solution if we exceed PostgreSQL single-node capacity.

Participants and Date

List who was involved in the decision and when it was made. This gives future readers someone to talk to if they have questions (assuming those people are still on the team), and it provides temporal context for understanding the constraints that existed at decision time.

Common Objections and How to Address Them

If you propose ADRs to your team, you will encounter resistance. Here are the most common objections and how to handle them.

"We Do Not Have Time to Write ADRs"

This is the most frequent objection, and it is the easiest to counter with simple math. A well-written ADR takes 15 to 30 minutes. A re-discussion of the same decision, triggered because nobody remembers the original reasoning, takes one to two hours with four to six people in the room. That is four to twelve person-hours. If a decision gets relitigated even once, the ADR has paid for itself many times over. Most significant decisions get questioned at least two or three times over their lifetime, especially as team membership changes.

The time investment is also front-loaded in the best possible way. You are writing the ADR at the moment when the context is freshest and the effort is lowest. Reconstructing that same context six months later would take far longer.

"Our Decisions Are Obvious. We Do Not Need to Document Them"

Decisions feel obvious in the moment because you have all the context loaded in your head. You just spent two weeks evaluating options. You had three discussions about tradeoffs. You read benchmark results and compared pricing models. Of course the decision feels obvious. But in twelve months, with three new team members who were not part of any of those conversations, nothing will be obvious. The "obvious" decision will look arbitrary, and someone will question it without understanding the constraints that shaped it.

A useful litmus test: if someone joined your team tomorrow and asked "why did you choose X?", could you point them to a document that answers the question? If the answer is no, it is not as obvious as you think.

"We Have a Wiki for That"

Wikis are where architectural knowledge goes to die. The problem is not the wiki itself. The problem is that wikis are mutable. Someone updates a page, and the original reasoning is overwritten. Someone reorganizes the wiki structure, and links break. Pages become outdated because nobody owns them, and there is no clear signal about whether the information is current.

ADRs solve this by being append-only and immutable. Each ADR is a snapshot of a specific moment. Old ADRs do not become stale because they were never meant to reflect current state. They reflect the state at decision time. If a decision is superseded, the new ADR links back to the old one, creating a clear chain of reasoning.

"Nobody Will Read Them"

This objection assumes that documentation is only valuable if everyone reads everything proactively. That is not how ADRs work. People read ADRs when they need them: during onboarding, when debugging an unfamiliar part of the system, when proposing a change that might conflict with a previous decision, or when someone asks "why is it built this way?" The value is in having the answer available at the moment the question arises, not in ensuring everyone has memorized every decision.

If you want to increase the chances that ADRs get read, make them easy to find. Keep them in a consistent location, use clear naming conventions, and reference them in code comments when relevant. A comment like // See ADR-023 for why we use async processing here is a powerful breadcrumb that connects code to context.

Where to Store ADRs

The storage question matters more than most teams realize. Where you put your ADRs affects whether people write them and whether people find them. There are three common approaches, each with distinct tradeoffs.

In the Repository

Storing ADRs in a docs/adr/ directory alongside the code is the most popular approach, and for good reason. ADRs are versioned with the code. They go through the same review process as code changes (pull requests). They are co-located with the thing they describe. The downside is discoverability. In a microservices architecture with dozens of repositories, searching for a specific decision across all repos is painful. Cross-cutting decisions (like "use gRPC for all inter-service communication") do not have a natural home in any single repo.

In a Wiki or Shared Document System

Wikis solve the discoverability problem. All ADRs are in one place, searchable, and accessible to everyone. The downside is the disconnection from code. ADRs in a wiki are not versioned with the codebase. There is no pull request review process. And wikis have a natural tendency to accumulate clutter that makes it harder to find relevant content over time.

In a Decision Intelligence Tool

The emerging approach is to use a dedicated tool that connects decisions to the broader context around them. A tool like Reattend lets you capture decisions alongside the related discussions, meeting notes, and supporting artifacts. Decisions are automatically linked to related context and become part of a searchable knowledge graph. This approach gives you the discoverability of a wiki with the contextual richness that neither a wiki nor a repo can provide on their own. You can use the Context Recall Timeline to trace how decisions evolved over time and understand the full history behind any architectural choice.

How to Get Your Team to Actually Write ADRs

Knowing that ADRs are valuable is one thing. Getting a team to adopt them consistently is another. Here are practical strategies that work.

Start With a Champion

That champion is you, the engineering manager. Do not delegate the introduction of ADRs to the team and hope they self-organize around it. Own the initiative. Set up the directory structure or tooling. Write the template. Explain the why in a team meeting. Make it clear that this is something you believe in and will support.

Write the First Five Yourself

Before asking anyone else to write an ADR, write five yourself. Retroactively document the last five significant architectural decisions your team made. This accomplishes two things. First, it creates immediate value. Those five ADRs will answer questions that people are already asking. Second, it sets the bar for quality, length, and tone. Your team will model their ADRs after yours, so make them good. Use the Decision Log Generator to create structured templates quickly, then fill in the details with your team-specific context.

Make It Part of the Design Review Process

The easiest way to ensure ADRs get written is to make them a natural part of an existing workflow. If your team does design reviews before starting significant work, add a requirement: every design review must produce an ADR. The ADR does not have to be written before the review. It can be written as an outcome of the review, capturing the decision that was made during the discussion. This way, the ADR is a byproduct of work you are already doing, not additional overhead.

Keep Them Short

A long ADR will not get written. If your template has 15 sections and expects two pages of content, people will skip it. The best ADRs are half a page to a page long. They take 15 to 30 minutes to write. They can be read in under three minutes. Optimize for consistency and coverage over depth. Twenty concise ADRs are worth more than three exhaustive ones.

Celebrate Good ADRs

When someone writes a particularly clear or useful ADR, call it out in your team retrospective. When an ADR saves someone time during debugging or onboarding, mention it publicly. Positive reinforcement is the most effective tool for building habits. When people see that ADRs are valued and appreciated, they are more likely to write them.

Beyond ADRs: Connecting Decisions to Context

ADRs are powerful, but they capture only one piece of the puzzle: the decision itself. The context around that decision lives in many different places. The Slack thread where three engineers debated the approach. The meeting notes from the design review. The pull request where the change was implemented. The customer feedback that drove the requirement in the first place. The incident report that revealed the limitations of the previous approach.

When all of this context is scattered across Slack, Google Docs, Jira, GitHub, and email, it is effectively lost. An ADR can reference these artifacts, but those references go stale. Links break. Slack messages get buried. Documents get moved.

The next evolution of decision documentation is connecting all of these pieces into a searchable, navigable knowledge graph. Instead of a static ADR that links to external resources, imagine a living record that automatically surfaces related context: the discussions that led to the decision, the code changes that implemented it, the follow-up decisions that built on it, and the outcomes that validated or invalidated the reasoning.

This is the vision behind Reattend. By capturing decisions, discussions, and context in a single system that understands the relationships between them, you get something more powerful than a collection of documents. You get a decision memory that grows smarter over time, helping your team build on past decisions rather than constantly rediscovering them.

Getting Started Today

You do not need to build a perfect ADR practice overnight. Start with one decision. Think about the last significant architectural choice your team made. Maybe it was a database selection. Maybe it was choosing between a monolith and microservices for a new feature. Maybe it was adopting a new framework or library. Whatever it was, take 20 minutes and write it down using the template above.

If you want a head start, use the Decision Log Generator to create a structured template that you can fill in with your specific context. It will give you the right format and prompt you for the information that matters most.

Then share it with your team. Tell them why you wrote it. Ask them to write the next one. In three months, you will have a library of decisions that new engineers can read in an afternoon, that saves hours of re-discussion every quarter, and that makes your entire team more effective at making and communicating architectural choices.

The best time to start writing ADRs was when you made your first architecture decision. The second best time is today.