ADR: Capture Context, Not Just Conclusions

Why it exists

Software teams repeatedly face the same technical crossroads, but institutional memory fades as people rotate, priorities shift, and code evolves without explanation. The result is a graveyard of unexplained patterns where every new engineer asks why a library was chosen, why a database was sharded a certain way, or why a service boundary exists. An ADR exists to freeze the reasoning that shaped a system at a specific moment in time, making it cheaper to onboard new teammates and safer to revisit old choices.

The mental model

Think of an ADR as a time-capsule for your brain. It is not a requirements document or a user manual; it is a snapshot of the forces, constraints, and fears that led to a decision. The goal is not to prove you were right, but to give future maintainers enough context to know when the original assumptions have changed and the decision should be overturned.

How it works

A typical ADR is a single lightweight file, often stored in a docs folder, numbered sequentially for easy reference. It follows a simple structure: a short title, a status such as proposed or accepted, the context describing the problem and constraints, the decision itself, and the consequences including accepted trade-offs and rejected alternatives. Once accepted, the record is treated as immutable; if the decision changes, you write a new ADR that supersedes the old one rather than editing history.

When to use it

Write an ADR when a decision is architecturally significant, meaning it is costly to undo, affects multiple teams or services, or establishes a pattern that others will follow. Examples include choosing a cloud provider, adopting an event-driven architecture, or mandating a specific authentication strategy. If skipping the write-up would force the next engineer to read thousands of lines of code to reconstruct your intent, you need an ADR.

When not to use it

Do not use an ADR for trivial choices like renaming a variable, patching a dependency, or picking a linter rule that has no structural impact. Also avoid using it as a living design document that gets updated continuously; that confusion turns it into overhead and trains teams to ignore it. If the decision can be reversed in an afternoon without side effects, the cost of documentation outweighs the benefit.

One canonical example

A platform team decides to move from REST to gRPC for internal service communication. They write ADR 0012 explaining that REST was causing payload bloat and schema drift, that GraphQL was rejected because it added client complexity without solving the binary protocol need, and that gRPC was chosen despite its poorer browser support because all traffic was service-to-service. Six months later, a frontend team asks about browser-facing endpoints. They read ADR 0012, immediately understand the boundary, and propose a new BFF pattern rather than forcing gRPC where it was never intended.