Architecture Decision Records

Architecture Decision Records for AI Systems

Why a two-page record of why a call was made is the highest-leverage document in an AI codebase — and how to write one whose revisit trigger fires before the next engineer re-litigates it.

In a normal service, an architecture decision ages in years. In an LLM system it ages in weeks: a provider ships a two-week deprecation notice, a model generation halves your token price, a prompt strategy that beat the golden set in March loses to a new default in June. The code shows what you chose; it never shows why — which candidate you rejected, at what price, and under what condition you’d change your mind. An Architecture Decision Record (ADR) is the durable answer to that question, and for AI systems its most important field is the one classic ADRs omit: the trigger that says when to reopen the file.