Documenting the 'Why': The complete guide to Architecture Decision Records (ADR)

We’ve all been there. You’re plunged into an old and critical corner of a project, on some sort of archaeological mission to implement a new feature.

Before long, an agonizing question emerges: “Why is it built this way?” The code is there, the why is visible, but the why has evaporated over time, swept away by team changes.

This loss of context is one of the most insidious forms of technical debt: knowledge debt.

It is precisely to fill this void that Architecture Decision Records (ADR) were conceived. They are a powerful and pragmatic remedy for the collective amnesia that plagues long-term software projects.

The debt of knowledge, a silent evil

The question “Why was it built this way?” isn’t intellectual curiosity. It’s a symptom of a problem that limits velocity, increases risk and frustrates developers.

If left unmanaged, this knowledge debt accumulates silently, making the system almost impossible to maintain or evolve.

Several factors explain this erosion of knowledge:

• Increasing complexity: Between microservices architectures, cloud-native ecosystems, event buses and the myriad of SaaS tools, every architectural decision is a complex compromise between dozens of variables. The reasoning behind these choices is anything but simple.
• The perpetual movement of teams: Turnover is a reality. Developers change projects or companies, taking with them a priceless part of the project’s history. Newcomers then find themselves faced with technical choices they can neither understand nor constructively challenge.
• The limits of traditional documentation: Wikis and other Confluence sites quickly become graveyards of obsolete documents. Comments in the code, on the other hand, explain how a line or function works, but rarely why an entire module has been structured in a certain way. They lack the macro perspective needed for architecture decisions.

Let’s imagine a concrete case: a team needs to integrate a new payment system.

They discover that the current authentication API, chosen three years ago, is not compatible. No one remembers why this specific API, and not a more standard one, was selected.

After days of research and hesitation, a former developer contacted by chance recalls that this choice was a temporary workaround for a performance constraint on a user type that no longer even exists today.

The team lost a week because of information that should have been logged. This is the kind of waste that ADRs help to avoid.

Anatomy of an ADR: more than just a document

To be effective, an ADR must be more than just a note. Its strength lies in its structure, which is both concise and rich in context. It’s crucial to understand that an ADR is not an exhaustive meeting report, nor a 50-page design document. It’s a focused artifact that crystallizes the result of architectural thinking.

Most effective ADRs are structured around the following sections, popularized in particular by Michael Nygard’s template:

• Title: This should be short and describe the decision taken. A good practice is to phrase it in an active way. For example, prefer “Adopt RabbitMQ for asynchronous communication” to a vague “Messaging system”.

• Status: An ADR is not set in stone, it lives. Its status reflects its life cycle. Common statuses are :

  • Proposed: The ADR is under discussion.
  • Accepted: The decision has been validated by the team and represents the current state of the architecture.
  • Replaced by ADR-XXX: A new decision has made this one obsolete. The new ADR is linked to it to maintain clear traceability.
  • Obsolete: The decision is no longer relevant (e.g. the department concerned has been decommissioned).

• Context: This is the heart of the “why”. This section describes the problem, the constraints and the forces at play. The context may include business requirements (e.g. “We need to reduce order processing time by 50%”), technical limitations (e.g. “Our current database can’t handle the load”), or specific team skills.

• Decision: This is the clear and direct statement of the chosen solution. It must be formulated without ambiguity. For example: “We’re going to use PostgreSQL as the main database for the new billing service. We will deploy a managed instance on AWS RDS.”

• Consequences: This is arguably the most important section, as it captures the essence of the architectural compromise. This is where the “why” comes into its own. It should honestly list :

  • Positive consequences: What we gain (e.g. “Better performance”, “Reduced licensing costs”, “Alignment with team skills”).
  • Negative consequences: What we lose, or the new problems we create (e.g. “Introduction of a new technology to maintain”, “Increased deployment complexity”, “This choice will make it more difficult to implement feature X in the future”).
  • Trade-offs: Options that were considered but rejected, and why. (e.g. “We considered MongoDB, but it was ruled out because our data is highly relational”).

By explicitly documenting the drawbacks and rejected alternatives, you offer an invaluable gift to future developers. You save them from re-exploring the same dead ends, and give them the context they need to assess whether yesterday’s compromises are still acceptable today.

Setting up the process

Knowing the anatomy of an ADR is one thing, effectively integrating it into a team’s workflow is quite another. To be successful, the process needs to be light, collaborative and seen as a help rather than a burden.

When to write an ADR?

The trap would be to document everything. ADRs are reserved for “architecturally significant” decisions. But what does this mean? Here’s a list of questions to help you decide:

• Does the decision introduce a major new technology, library or framework?
• Does it have a significant impact on system security, performance or scalability?
• Does it change the way developers will work or build functionality?
• Is it difficult or costly to undo?
• Does it affect several teams, departments or modules?

If you answer “yes” to one or more of these questions, an ADR is most likely warranted.

A code-based collaborative process

The best approach is to treat ADRs as code. Integrate them into your existing review process:

1. Draft: A developer writes an ADR to a new Git branch. Status is Proposed.
2. Review: He opens a Pull Request (or Merge Request). The team discusses the proposal asynchronously in the PR comments. This is the time to challenge assumptions, propose alternatives and enrich the “Consequences” section.
3. Decision: Once consensus has been reached (or the decision taken by the technical lead after discussion), the status of the ADR is updated to Accepted.
4. Merge: The RP is merged. The decision is now officially recorded in the project history.

This workflow guarantees transparency, traceability and inclusiveness. Every team member has a chance to contribute.

Where to store ADRs?

The golden rule is simple: ADRs live with the code. Place them in the same Git repository as the project they concern. A folder like /docs/adrs or /doc/architecture/decisions at the root of the project is ideal. Why?

• They are versioned at the same time as the code.
• They are accessible to anyone who clones the project.
• They can’t be lost or become obsolete in a forgotten wiki.
• When you consult an old version of the code, you can also see the decisions that were in force at the time.

Tooling: keep it simple

You don’t need a complex system. You can start with :

• Markdown files.
• A simple naming convention, e.g. NNN-title-of-the-decision.md (e.g. 001-adopter-postgresql.md).

For those who like to automate, command-line tools like adr-tools can help you create, link and manage ADRs. But remember: the tool is secondary, it’s the practice that counts.

Long-term strategic benefits

Adopting ADRs requires an initial effort, but the benefits far outweigh this investment.

• Onboarding on steroids: For a newcomer, the ADR file is a gold mine. In just a few hours’ reading, he or she can understand the evolution of the project, the structuring choices made and the reasons behind them. It’s a far more effective integration gas pedal than any presentation session.

• An architectural time machine: When a new business requirement calls into question a past choice, ADRs are your best ally. They allow you to “replay” the decision with all its original context. Are yesterday’s constraints still valid today? Are the compromises made back then still acceptable? This allows refactoring decisions to be made on solid foundations, not on hunches.

• Risk reduction and informed decision-making: The formal process of writing and reviewing an ADR forces clarity. It forces teams to verbalize pros and cons, exposing potential risks before the first line of code is written. Collective discussion helps to spot problems that a single person might not have seen.

• Breaking down silos and promoting alignment: When architecture decisions are made behind closed doors, they create misunderstanding. By making ADRs visible to all via Pull Requests, you democratize the process. Information circulates and collective ownership is reinforced.

Overcoming obstacles and preconceived ideas

Despite its advantages, the introduction of ADRs can meet with resistance. Here’s how to deal with the most common objections.

• “It’s too much bureaucracy!” The real bureaucracy is the three meetings and two days of archaeology needed to understand a decision taken six months earlier. An ADR is a one-time investment that pays dividends for years. It’s a “just enough” process to avoid chaos.

• “We’re moving too fast for that.” This objection confuses speed with haste. ADRs don’t slow things down, they speed things up sustainably. They avoid costly architectural errors which, months later, will paralyze the project and destroy the team’s velocity.

• “My team will never adopt it.” Don’t try to impose a big change all at once. Start small. For the next significant decision, offer to draft an ADR as an experiment. Lead by example. When the team sees for themselves the clarity this brings, adoption will follow naturally.

• The myth of the “perfect ADR ”. Don’t expect the perfect template or the literary style of a great author. An imperfect ADR that captures 80% of the context is infinitely more valuable than no ADR at all. Perfection is the enemy of good. The goal is clarity, not perfection.

Communicating with the future

At the end of the day, Architecture Decision Records are not a chore of documentation. They are a deliberate act of communication with your future team members, and with your “future you”. They preserve a project’s most precious and volatile asset: the “why”.

Adopting ADRs is the sign of a mature engineering culture, which prioritizes long-term maintainability and shared knowledge over short-term velocity. It’s a conscious choice to build systems that last.

So, for your next significant decision, don’t just make it. Document it. Write your first ADR.