Write the ADR before you write the code

TL;DR. Based on Clouditive assessment data across twelve engagements, approximately 63 percent of architectural decisions get revisited within six months. None of the revisited decisions had a written record of why the original choice was made. The fix is not retrospective documentation — it is writing the ADR before the build, in the sequence: decide, approve, build. The document does not need to be long. It needs to survive the engineer who made the decision leaving the team.

The tool gets chosen in a meeting. The reason gets lost in a Slack thread.

Three months later, nobody remembers the tradeoffs. The context is gone. The decision stays, but the reasoning behind it has evaporated. A new engineer joins, sees a choice that looks wrong without the context that made it right, and reverses it. The team does the work twice. Sometimes three times.

This is not a documentation problem. It is a planning problem. Teams pick tools before picking a reason. Terraform gets adopted because the senior engineer likes Terraform, not because someone wrote down the constraints that made Terraform the right choice for this system at this scale in this team's context. ArgoCD gets adopted because it was in a conference talk. Datadog gets adopted because it was in a job description. None of these adoptions are necessarily wrong. The problem is that without the reasoning in writing, the decision is invisible to everyone who was not in the room.

The cost compounds. Based on Clouditive assessment data across twelve engagements, approximately 63 percent of architectural decisions get revisited within six months. In that same set of engagements, none of the revisited decisions had a written record of why the original choice was made. The team doing the revisiting was not malicious. They were uninformed. The information that would have told them not to reverse the decision did not survive the original decision-making meeting.

What an ADR actually is — and why the word "before" is load-bearing

An Architecture Decision Record (ADR) is a short document that captures a single architectural decision: what problem it solves, what options were considered, what was chosen, why, and what the known tradeoffs are. The format was popularized by Michael Nygard's 2011 blog post and has been adopted widely, though implementation quality varies enormously.

The critical word is "before." The ADR is not retrospective documentation of what was built. It is prospective documentation of what will be built and why. Writing it before building serves two purposes that retrospective documentation cannot.

Writing forces clarity. The act of stating "the problem is X, the options are A, B, and C, we chose B because..." surfaces assumptions that were implicit in the meeting discussion. Engineering teams regularly discover, when forced to write down the problem they are solving, that they were solving slightly different problems. The ADR is where those differences get resolved before they manifest in incompatible implementations.

The ADR also creates accountability. Once the problem, the options, and the chosen path are in writing with stakeholder sign-off, the build phase has a clear mandate. Scope creep becomes visible. Changes in direction require a new ADR, not a Slack message. The team that was going to "add a few features" while building the original requirement now has to acknowledge explicitly that they are changing the decision.

Why most ADR efforts collapse at one of three points

Most teams that have tried ADRs and abandoned them failed at one of three points.

The first failure is writing the ADR after the fact. Post-hoc ADRs are archaeology, not planning. The team is reconstructing the reasoning from memory, which means they are writing the reasoning that survived, not the reasoning that was actually weighed. Options that were seriously considered and rejected tend to disappear from retrospective ADRs. The document then fails at its core purpose: when the next engineer asks why option A was not chosen, the ADR says "we chose B" without recording what made A inadequate.

The second failure is treating the ADR as a bureaucratic checkpoint. Teams that require ADR approval before any tool adoption quickly produce ADRs that are written to justify decisions already made, reviewed by people who do not push back, and filed to fulfill a process requirement. The document exists. The reasoning does not. This is the same as no ADR, with more administrative overhead.

The third failure is writing ADRs only for tool choices and not for structural decisions. The Terraform vs. Pulumi decision gets an ADR. The decision about how to structure environments, how to define ownership boundaries between platform and application teams, or how to sequence the observability buildout relative to the IDP buildout does not. These structural decisions are the ones most expensive to reverse and most invisible without documentation.

Decide, approve, build — the sequence that reduces the 63 percent reversal rate

The sequence is decide, approve, build. The inversion of this sequence — build, then retrospectively document, or build and never document — produces the 63 percent reversal rate.

Write the ADR first. State the problem in one to three sentences. List the options considered, including the option of doing nothing. For each option, note the key tradeoffs: not a comprehensive analysis, but the factors that would lead a reasonable engineer to prefer one over another. State the chosen path. State the known consequences: what additional work the choice creates, what it forecloses, what the team will need to learn.

A good ADR does not require extensive research. It requires honest accounting of what the team actually knows and decided. Here is what this looks like for a real decision:

ADR-001: Container Orchestration Strategy

Status: Approved

Context: We need container orchestration for 47 microservices across 3 environments.

Decision: Kubernetes (AKS) over ECS. Multi-cloud portability, team expertise, CNCF ecosystem.

Tradeoffs: Higher complexity vs ECS. Mitigated by managed AKS plus Crossplane abstraction.

Consequences: Team needs CKA training. Estimated 6-week ramp. Crossplane abstracts Day 2 ops.

That is 60 words. It is not comprehensive. It is the minimum honest record of what was decided and why. An engineer reading it six months later knows why ECS was not chosen (portability requirements, team expertise), what was accepted as a cost (training, complexity), and what was done to mitigate that cost (managed service, abstraction layer).

Before building, review the ADR with stakeholders and get sign-off. This step is where most ADR processes get soft. Sign-off feels like bureaucracy. Teams skip it or perform it as a formality. The purpose of sign-off is not to create a paper trail — it is to surface disagreements before they appear in code. In practice, most stakeholder reviews of well-written ADRs take fifteen minutes. A reviewer who agrees confirms the team is not missing something obvious. A reviewer who disagrees either improves the decision or confirms their own misalignment with the direction, which is also important to know before building.

Then execute. The ADR is the receipt that protects everyone. If the requirements change mid-build, that is a new ADR. If the chosen solution proves technically infeasible, that is a new ADR with a documented reason for the change. The original ADR is not deleted or modified retroactively. It is superseded, with a reference to what replaced it and why. This creates a decision log that survives team turnover.

Context decays within weeks — the ADR is the only thing that survives it

Decision context includes ambient factors that are not part of the formal record: what the team was prioritizing at the time, what alternatives were deprioritized and why, what the competitive or business context was, what the senior engineer's specific concern was that drove the choice. That ambient context dissipates within weeks. Without a written record, the decision at month six is just a number in a configuration file with no accessible reason.

The implication for onboarding is direct. An engineer who joins at month four and encounters a configuration choice they do not understand has two options: ask someone (if that someone is still on the team and remembers), or investigate (which may lead them to change something that was right for reasons they cannot see). ADRs give them a third option: read the record and understand.

Clouditive engagement data shows that teams without ADR discipline average 21 days to first PR for new engineers. Teams with ADR discipline targeting 5 days close that gap primarily by eliminating the orientation time engineers spend trying to understand decisions without access to the reasoning.

Five patterns that reveal ADR discipline is missing

Not every engineering organization recognizes when their decision process has degraded. These five patterns each identify something that ADR discipline addresses directly.

When the same pipeline produces an 18-minute deploy for one engineer and a 97-minute deploy for another, the procedure lives in people, not in documentation. Alice knows the shortcut. Bob does not. The ADR for the deployment process, including the known exceptions and the reasoning behind each decision in the pipeline, eliminates that asymmetry.

When the team has no record of why they chose their stack, Q1 Terraform gives way to Q2 Pulumi which gives way to Q3 Terraform. The second switch back to Terraform would not have happened if the first ADR had recorded why Pulumi was unsuitable.

When onboarding takes 3 weeks, documentation lives in someone's memory and onboarding is bounded by that person's availability and patience. When decisions are in ADRs, a new engineer orients themselves asynchronously with primary sources.

When incidents repeat, it is because the hero fixes it but nobody writes it down. The incident runbook is a specialized ADR for operational decisions: here is what broke, here is what fixed it, here is why we believe it is the right fix and not a workaround.

When leadership cannot tell if the platform is getting better, there is no baseline, no delta, no story. The ADR log, combined with outcome metrics, lets engineering leaders answer the question "are our architectural decisions improving?" with data — which decisions were reversed, which ones held, what did the reversals cost in engineering time.

The heuristic for deciding which decisions need an ADR

A useful heuristic: write an ADR for any decision that would cost more than one sprint to reverse if it turns out to be wrong.

Choosing which CI/CD tool to adopt: ADR. Choosing the naming convention for environment variables: not an ADR (reversible cheaply). Choosing how to structure service ownership across teams: ADR. Choosing which code formatter to enforce: not an ADR.

The heuristic keeps ADR volume manageable while capturing the decisions that matter. An engineering organization making one major platform decision per month needs one new ADR per month. Twelve ADRs per year: a document set any engineer can read in an afternoon when they join. Compare that to what they face without ADRs: a codebase full of choices with no accessible reasoning and several people who have already left.

The ADR is not a burden. It is the minimum honest record of what was decided and why. Without it, the decision lives in someone's head until they leave. With it, the decision lives in version control until someone writes a better one.

Frequently asked questions

How long should an ADR be?

As short as it can be while capturing the problem, the options considered, the choice, and the known tradeoffs. The example in this post runs 60 words. A good ADR for a significant infrastructure decision might reach 300 words. If it exceeds 500 words, it is probably covering too much ground and should be split. The constraint is not length — it is that the reasoning must survive the people who were in the room.

What decisions are too small for an ADR?

Use this heuristic: write an ADR for any decision that would cost more than one sprint to reverse if it turns out to be wrong. Choosing the naming convention for environment variables does not need an ADR. Choosing the CI/CD tool, the service mesh strategy, or how to structure environment ownership does. Twelve ADRs per year is a document set any engineer can read in an afternoon.

Why do most ADR programs fail within six months?

Three failure modes: writing the ADR after the decision is already made (which produces archaeology rather than planning), treating it as a bureaucratic checkpoint where sign-off is performed rather than sought, and writing ADRs only for tool choices while ignoring structural decisions. Structural decisions — how teams own services, how environments are sequenced, how the platform and application teams divide accountability — are more expensive to reverse and more invisible without documentation.

How does ADR discipline affect onboarding speed?

Clouditive engagement data shows that teams without ADR discipline average 21 days to first PR for new engineers. Teams with ADR discipline targeting 5 days close that gap primarily by eliminating the orientation time engineers spend trying to understand decisions without access to the reasoning. The ADR gives new engineers a third option beyond asking someone or guessing: read the record and understand.

---

If you want to understand where your platform team's decision documentation stands relative to the Foundations Framework maturity model, the free Platform Score includes an ADR and documentation dimension. The Foundations Assessment produces a full documentation audit as part of the Horizon phase diagnostic.

For a deeper read on the five signs your platform is running on tribal knowledge rather than documented decisions, read 5 signs your platform team is stuck in ad-hoc mode.

For the distributed team coordination infrastructure that ADRs are the foundation of, read scaling distributed engineering teams without losing speed or coherence.

For why IDP decisions without ADRs produce the regrets described in the build-vs-buy post, read IDP build vs. buy — how to decide without regretting it.