{"canonical_url":"https://engineer.company/glossary/architecture-decision-record/","content_markdown":"# Architecture decision record\n\n## What it is\n\nAn architecture decision record, often abbreviated ADR, is a short account of\na consequential technical choice. It says what the team decided, which\nconditions made the decision necessary, what credible options it considered and\nwhat consequences it accepted. The choice might concern how to store facts,\nwhere a system boundary lies, how teams integrate or what happens during a\nfailure. A reader arriving later can use the record to understand why this\ndesign exists and which assumptions still apply.\n\nA few fields carry most of the work. An identifier and a date make the record\neasy to cite. A short status indicates whether a decision is proposed,\naccepted or superseded. The context identifies the problem and constraints.\nThe decision describes what the team will actually do. Consequences cover\nbenefits and obligations, such as another service to operate, a slower\ntransition or a migration that must be rehearsed. Include enough detail about\noptions to explain the tradeoff without recreating the full discussion.\n\nUse the same publication path reviewers already trust. A team may keep\nMarkdown records beside its code and link them from the change that implements\nthe decision. A team designing a service across several repositories may keep\na shared index and reference the same record from each change. The record's\nvalue comes from readable reasons and a stable address. Its template is a\nmeans of capturing those reasons consistently.\n\n## Why it matters\n\nCode is good at preserving what exists. It explains the history only\npartially. A reader may see two databases and assume that one should be\nretired, when the split was a temporary measure to isolate a risk while a\nsupplier changed its export. The written decision can clarify what the team\nwas protecting, why the alternative was viable and what event makes it time\nto reconsider. That avoids repeating an investigation from scratch.\n\nThe record also helps people disagree productively. A proposal can say that a\nnew dependency would spare the team from developing a scheduler but require\nan operator who can restore its state. A reviewer can question the cost or the\navailability of that operator. The tradeoff is visible to people outside the\nimmediate implementing pair, including the team that will operate the service.\nOnce accepted, the same account gives a handover reader a way to understand\nwhere responsibility belongs.\n\nThe time spent writing should match the effect of revisiting the choice.\nChanging a label normally belongs in the change history. Changing which\nservice owns the ledger or how an application handles duplicate payments is\ncostly to undo and has consequences for several readers. A short record\nwritten during the decision preserves those reasons before the team forgets\nearlier alternatives. Keep the evidence close enough that another engineer\ncan confirm which reading was available on that day.\n\n## What it looks like in practice\n\nThe portfolio's account of [a platform's founding technical decisions](/portfolio/set-the-platforms-founding-technical-decisions/)\ndescribes choosing core technologies while shaping the product and its\ntechnical direction. That case shows the kind of decision worth preserving.\nThe following fictional example illustrates how an ADR could record a similar\ntradeoff about ownership. It is written for this article.\n\nSuppose a shipping service has a live order database and a read-only status\npage. Teams have been debating whether the status page should read the order\ndatabase directly. The context is that dispatch receives late status events and\nsupport needs a public view that cannot disclose another customer's order.\nThe decision is to serve the view from a separate read model, updated from\napproved fields only. A direct read would start with fewer components and\nusually show fresher data, but would put public traffic and a new permission\nboundary next to the system of record. Reusing a nightly export would be\nsimpler still, but would leave same-day delivery changes invisible.\n\nThe consequences should drive work. A lag indicator tells the support\nteam when to fall back to its internal procedure. A contract check catches\nan accidental new field. Someone owns the update job and its alert. The\nteam agrees to revisit the choice if lag exceeds the agreed tolerance in two\nbusy weeks, or if the separation requirement changes. The record links to\nthe design review and the test. A maintainer can see the cause of the extra\ncomponent and the evidence needed before replacing it.\n\nWhen replacing the choice, create another record, link both directions and\nmake the old entry's status clear. Preserve the dated reason that was valid\nfor the previous design. People investigating an older system version still\nneed that history. An index with short titles and statuses lets readers\nfind the live decision without reading a chain of reviews.\n\nBefore returning a status, the public endpoint verifies that the viewer has access to that specific order. Test rejection of another customer's order as well as the exact allowed response fields.\n\n## Where it goes wrong\n\nA record is weak when it lists one preferred option and a caricature of\neverything else. Give alternatives the fairest version the team considered.\nReaders should understand why an option would have been attractive in a\ndifferent situation. Ground important claims in the benchmark, standard or\nconstraints that actually informed the decision. A copied template should\nleave room to describe a decision that depends on legislation, capacity or\nprevious commitments.\n\nA second mistake is to list advantages and leave the costs unowned. A new\ndatabase, a second application or a shared queue changes someone else's\nworking day. Include the operational handover, security boundary or\nmaintenance cost that follows. Assign important obligations to people and\nchecks where appropriate. If the consequences cannot be tested immediately,\nname what would be observed and when the team expects to learn.\n\nFinally, keep the record small and timely. A folder of uniform documents\nwhose milestones no longer match the work is harder to trust than a handful\nof precise decisions. Separate the decision's reasoning from a general\ntutorial and link to changing operational procedures. When a continuation\nbecomes a new choice, preserve both decisions and give readers a reliable\nroute to the current one.\n\n## Further reading\n\n- [AWS guidance on the architecture decision record process](https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html)\n- [Microsoft Azure Well-Architected guidance on decisions](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record)\n- [UK government architectural decision record framework](https://www.gov.uk/government/publications/architectural-decision-record-framework)\n\n\u003chttps://engineer.company/glossary/architecture-decision-record/\u003e\n","date_modified":"2026-11-19T19:18:49Z","description":"Use a short decision record to preserve a design choice, its alternatives and the evidence that would justify revisiting it.","formats":{"gemtext":"https://engineer.company/glossary/architecture-decision-record/index.gmi","gopher":"https://engineer.company/glossary/architecture-decision-record/gophermap","html":"https://engineer.company/glossary/architecture-decision-record/","json":"https://engineer.company/glossary/architecture-decision-record/index.json","markdown":"https://engineer.company/glossary/architecture-decision-record/index.md","pdf":"https://engineer.company/glossary/architecture-decision-record/index.pdf"},"kind":"page","language":"en","title":"What is an architecture decision record?","url":"https://engineer.company/glossary/architecture-decision-record/","version":1}