← Stackzilla Blog

Architecture Decision Records: Save the Reason, Not Just the Diagram

Published November 19, 2026 · 3 min read · architecture, documentation, engineering teams, technical leadership

Write short decision records that explain constraints and tradeoffs so future developers know when an old choice should change.

A repository can tell a new developer that the application uses a relational database. It usually cannot tell them why the team rejected a document database, which constraints mattered, or whether those constraints still apply. An architecture decision record preserves that missing reasoning. It is not a full design document or a transcript of every meeting. It is a compact explanation of a consequential choice in its original context. ## Record the problem and the constraints Start with the decision the team needed to make. Name the requirements that shaped it: consistency, data volume, team experience, operational ownership, delivery time, or compatibility. Separate confirmed facts from assumptions. “The product currently has one region” is different from “we expect to remain in one region.” Future engineers need to know which parts can change. Avoid retroactively making every decision sound inevitable. Alternatives may have been reasonable. Explaining their disadvantages fairly helps readers evaluate the choice rather than simply inherit it. ## Keep the decision small enough to understand Describe the chosen option and the most relevant alternatives. Include consequences, including costs and limitations the team knowingly accepted. For example, choosing a modular monolith might reduce operational complexity while requiring stronger module boundaries. Choosing asynchronous processing might improve resilience while making state transitions harder to explain in the interface. Link to supporting benchmarks, prototypes, or requirements when available, but summarize the reasoning in the record. A link to a vanished chat thread should not be the only explanation. ## Make revision possible without rewriting history Give records a clear status, such as proposed, accepted, or superseded. When a decision changes, create a new record explaining the new context and link the old one. Do not silently edit the past to make it match the current architecture. The value of the history is understanding how the system got here. Include review triggers when useful: a traffic threshold, a new compliance requirement, or evidence that an assumption no longer holds. That is more actionable than declaring that the team will revisit the decision “later.” Use decision records selectively. Requiring one for every variable name creates paperwork and hides the important choices. Focus on decisions that are costly to reverse, affect multiple teams, or establish conventions future work depends on. A good record may fit on a page. Its success is not measured by length, but by whether a future engineer can understand the tradeoff and recognize when a different answer would now be appropriate. ## Further reading - [Michael Nygard: Documenting architecture decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) - [AWS: Architectural decision records](https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html)

Read the full article on Stackzilla →