Governance
Models and providers change every few months, and the reason behind a choice is gone sooner than the code. A short record per decision keeps it.
Nov 5, 2026 · 4 min read
Six months into an agent project someone asks why support tasks go to a mid-tier model, or why approvals sit in the tool gateway and not in the agent. The code shows what was built. It does not show what was considered. That is the gap an architecture decision record, or ADR, fills.
Michael Nygard proposed the format in 2011: one short document per significant decision, with a title, a status, the context, the decision and its consequences. The records are numbered sequentially, and a number is never reused.
If a decision is reversed, keep the old record and mark it as superseded, with a pointer to its replacement. The rejected alternatives are often the most useful part for a future reader, because they stop the team from re-running the same argument.
Example, invented for illustration: ADR-007, Route classification to a small model. Status: accepted. Context: classification dominates volume and does not need deep reasoning. Decision: we will send classification to the smallest tier and escalate on low confidence. Alternatives rejected: one large model for everything, because of cost. Consequences: we must keep an evaluation set to catch regressions when the small model changes.
Tell us about one process. We'll show you how an agent could handle it, and what to measure to confirm it's working.