Architecture Decision Records
ADRs for AI systems: a reusable template plus three fully worked records (model provider choice, build-vs-buy guardrails, sync-to-async migration) — each with an explicit revisit trigger.
Last updated
After this section you can
- Explain why AI/LLM systems need ADRs more than conventional services — fast-churning model versions, invisible reasoning in code, false reversibility, and default re-litigation — and why the revisit trigger is the field that makes an AI ADR
- Apply a reusable ADR template (Title, Status, Date, Context, Decision, Consequences, Alternatives, Revisit trigger) stored as append-only numbered Markdown, transitioning status rather than deleting history
- Write numbers-driven ADRs for the three recurring AI decisions: model provider choice, build-vs-buy guardrails, and a sync-to-async queue+webhook migration
- Frame an architecture choice in an interview as an ADR with an explicit, observable revisit trigger instead of asserting a single permanent answer
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.