Architecture Decision Record Template for AI Systems

An architecture decision record (ADR) is a short, dated document that captures one significant design decision: the context, the options considered, the choice and its consequences. For AI systems, an architecture decision record template needs a few more fields than the classic version, because AI decisions rest on facts that change quickly: the model version, the evaluation evidence, the data classification, the cost per request and the date the decision should be looked at again. This guide gives you that template, a filled-in example and the practices that keep a decision log useful.

What an ADR is, and where the format comes from

The format most teams use comes from a 2011 post by Michael Nygard, “Documenting Architecture Decisions.” He proposed a short record for each architecturally significant decision with five parts: a title, a status, the context (the forces at play), the decision and the consequences, including the negative ones. Records are numbered, kept in the repository and never deleted. Later variants such as MADR (Markdown Any Decision Records) add explicit decision drivers and a list of the options considered.

An ADR is not a design document. A design document describes a whole system; an ADR records one decision, in a page or two, when it is made. After a year, the decision log explains why the system looks the way it does, which is the question every new engineer, auditor and review board member asks.

Why AI systems need ADRs more than most

A choice of relational database can hold for a decade. AI decisions age fast, and they rest on evidence with a shelf life.

• Model choice. The best fit on your evaluation set at a point in time. Providers deprecate versions on their own schedule.
• Hosting. Managed API, cloud endpoint or self-hosted open-weight model, which depends on volume, data classification and residency.
• Retrieval design. Changing the embedding model usually means re-indexing everything, so the original reasoning matters.
• Guardrails. Input and output filters are often tuned once and never revisited.
• Evaluation thresholds. If nobody wrote down why the pass mark was set there, nobody can defend it later.
• Vendor dependence. Every proprietary feature raises the cost of leaving. An ADR is where that cost is admitted in writing.
• Data residency. Where each provider processes prompts and outputs, and which data classifications may go there.

An AI ADR has to record not only what was decided, but what evidence supported it and what would make it wrong.

Which AI decisions deserve an ADR

Write an ADR when a decision is costly to reverse, affects more than one team, or will be questioned later by someone who was not in the room.

Decision type	Example	Write an ADR when
Model selection	Which model serves a customer-facing assistant	A model is chosen for a production workload, or replaced
Hosting and provider	Managed API versus self-hosted open-weight model	A new provider or hosting pattern enters the estate
Retrieval design	Embedding model, chunking strategy, vector store	The choice forces a re-index or a new component to change
Orchestration	A framework such as LangGraph versus plain code or a workflow engine	A pattern will be reused by other teams
Guardrails and safety	Where prompt injection and output filters run	Controls are set or relaxed for a moderate or high tier system
Evaluation	The suite and pass thresholds that gate release	Thresholds are set, lowered or replaced
Data	Which data classifications may reach which model	Sensitive or regulated data goes to a new destination
Agent autonomy	Whether an agent may write to a system of record	An agent gains a write tool or a higher autonomy tier
Cost and capacity	Caching, routing to smaller models, reserved capacity	A spending commitment or a cost ceiling is set
Exceptions	A departure from the reference architecture	Any time a standard is waived

The triggers overlap with the ones that bring a design to an AI architecture review board. That is deliberate. A board decision should end in an ADR, and an ADR is the natural thing to bring to the board.

The template

The fields below combine the classic ADR with AI-specific additions. Copy the block into a Markdown file, replace the bracketed parts and keep it to two pages at most. Link to evidence rather than pasting it in.

# ADR-[number]: [Short decision title, stated as the choice]

Status: [Proposed | Accepted | Superseded by ADR-x | Deprecated]
Date: [YYYY-MM-DD]
Deciders: [Names and roles]
Consulted: [Security, data, risk, others as needed]
Scope: [System, platform layer or whole estate]
Risk tier: [Low | Moderate | High, from the governance framework]

## Context
[The problem, the constraints and the forces in tension. Two to four
short paragraphs. Name the workload and the users.]

## Decision drivers
- [Quality bar the workload must meet]
- [Data classification and residency constraints]
- [Latency, volume and cost limits]
- [Team skills and operating model]

## Options considered
1. [Option A]: [one line on how it fits, one on its main drawback]
2. [Option B]: ...
3. [Option C, including "do nothing" where relevant]: ...

## Decision
[The choice, in one or two sentences, stated plainly.]

## Model and version
- Model(s): [provider, model, version or deployment name]
- Pinning: [how the version is fixed, and who may change it]

## Evaluation evidence
- Suite: [link to the evaluation set and harness]
- Results: [link to the run that supported this decision]
- Thresholds: [the pass marks for release and for continued operation]

## Data
- Sources: [systems and datasets used for retrieval, tuning or prompts]
- Classification: [highest classification involved]
- Residency and retention: [where data is processed and how long logs are kept]

## Cost assumptions
- [Expected volume, unit price assumed, monthly estimate, ceiling]

## Consequences
- Positive: [what gets easier]
- Negative: [what gets harder, including lock-in]
- Follow-up work: [tasks this decision creates, with owners]

## Fallback and exit plan
[What happens if the model or provider becomes unavailable, and
what it would take to move off this choice.]

## Review
- Review by: [date]
- Revisit if: [model deprecation notice, price change above x,
  evaluation score below threshold, new data classification,
  new regulation, a better option passing the same suite]

## Links
[Related ADRs, review board decision, registry entry, tickets]

Three fields deserve a note.

Model and version. Record the exact version or dated deployment, not a model family name. “Uses the provider’s flagship model” stops meaning anything at the next release. Say who may change the pin.

Evaluation evidence. Link to the run, not a summary. The threshold matters as much as the score: a reviewer needs to know what “good enough” meant at the time to tell whether a later result is a regression.

Revisit triggers. This is the field that makes an AI ADR work. A review-by date catches slow drift; named triggers catch sudden change, such as a deprecation notice, a price change or a new data class. Wire the predictable ones to alerts where you can.

An illustrative example

The record below is illustrative. The company, workload, providers and figures are invented to show how the fields read when filled in.

Field	Example value
Title	ADR-014: Serve the policy assistant from a managed endpoint in the primary cloud
Status	Accepted
Deciders	AI platform owner, enterprise AI architect, security architect
Risk tier	Moderate (employee-facing answers about internal policy, with sources cited)
Context	The HR policy assistant moves from pilot to production. Prompts include confidential documents. The pilot used a direct provider API with a shared key.
Decision drivers	Confidential data must stay in the primary cloud tenancy; answers must cite sources; median response under five seconds; monthly cost within the approved budget
Options considered	(1) Keep the direct API: data leaves the tenancy, keys unmanaged. (2) Managed endpoint in the primary cloud through the LLM gateway: meets residency, small quality gap. (3) Self-hosted open-weight model: GPU operations the team cannot yet staff.
Decision	Option 2. All calls go through the gateway to a managed endpoint in the primary cloud region.
Model and version	One hosted model, dated version pinned in gateway configuration; changes need the platform owner and a passing evaluation run
Evaluation evidence	Policy question set of a few hundred graded questions; pass marks set for groundedness, citation accuracy and refusal of out-of-scope questions; link to the run
Data	HR policy library (confidential); no employee records; prompts and outputs retained per the internal logging standard
Cost assumptions	Expected daily volume and unit price recorded, with a monthly ceiling enforced at the gateway
Consequences	Positive: residency met, keys managed, usage attributed. Negative: dependent on one cloud provider’s model catalog; a slightly lower score on one question category, accepted and noted.
Fallback and exit	Gateway route to a second approved model, tested quarterly; the retrieval layer is provider-neutral, so a move requires no re-index
Review by	Six months from acceptance
Revisit if	Deprecation notice for the pinned version; unit price change of more than an agreed margin; groundedness below threshold for two weeks; employee records added to scope

If the provider announces a deprecation, the team knows which suite to rerun, which thresholds to meet and which fallback was already tested. If someone asks why the pilot’s direct API was dropped, the answer is in option 1.

How ADRs connect to the rest of your AI governance

The reference architecture. An enterprise AI reference architecture has a logical view, an implementation view and a decisions log. The ADRs are that log. Each approved component should point to the ADR that put it there.

The review board. A board decision should produce or ratify an ADR, with any conditions written into the consequences. “Options considered” maps directly to the board’s submission pack.

The risk tiers. Use the tiers from your AI governance framework. A low tier system on approved patterns rarely needs its own ADR. A high tier system should have ADRs for its model, data flows, guardrails and evaluation thresholds, because those are what an impact assessment and an auditor will ask about.

The agent registry. The AI agent registry template records what is deployed now; the ADR records why. Link the two both ways. A change that hits a registry re-review trigger, such as a new write tool, should usually produce a new ADR.

Where to keep them

Keep ADRs in version control, as Markdown, next to the code they govern. A common convention is a docs/adr or docs/decisions folder in each repository, with files named by number and title. Decisions that span the estate, such as the approved model providers, live in a shared architecture repository that other repositories link to.

This docs-as-code approach means a proposed ADR is a pull request, reviewed the way engineers already review code, and it ships in the same change as the code it explains. History comes from version control rather than a wiki page anyone can edit without a trace.

Tooling is optional. Plain Markdown and a numbering convention are enough for most teams. Tools such as Nat Pryce’s adr-tools (a command-line helper for creating and linking records) and Log4brains (which publishes a decision log as a browsable site) can help once the log grows. Avoid putting ADRs in a system the engineers do not open.

The lifecycle: proposed, accepted, superseded, deprecated

Every ADR carries a status, and the status is the only part of an accepted record that should change.

1. Proposed. The record is drafted and under review, usually as an open pull request.
2. Accepted. The deciders agree. The record is merged and is now part of the log.
3. Superseded. A later ADR replaces the decision. The old record gets “Superseded by ADR-x” and the new one says “Supersedes ADR-y.”
4. Deprecated. The decision no longer applies but nothing replaced it, for example because the system was retired.

To supersede a decision, do not edit the old record. Write a new ADR with its own context, options and evidence, and link the two. For AI systems this happens often, and that is healthy: a model upgrade or a new threshold each deserves its own record.

Common mistakes

• Writing ADRs after the fact. A record written months later explains the outcome, not the reasoning.
• Recording the winner only. Without the rejected options, the same debate returns with the next team.
• Evidence by assertion. “Evaluated and performed well” is not evidence. Link the run and state the threshold.
• No revisit triggers. The decision outlives its assumptions.
• Editing accepted records. It removes what an auditor or incident review needs. Supersede instead.
• Too many trivial records. If every prompt edit gets an ADR, people stop reading them. Let routine changes go through the evaluation suite.
• A log nobody consults. Make “is there an ADR for this?” the first question on every design review.

Getting started

1. Agree the template above, removing fields you will not fill.
2. Create an ADR folder in each AI repository and a shared repository for estate-level decisions.
3. Write ADR-001 recording the decision to use ADRs, with the trigger table as its content.
4. Backfill records for the decisions people already argue about: providers, hosting, vector store, gateway and evaluation thresholds.
5. Add “link the ADR” to the review board submission pack and the release checklist.
6. Set alerts for predictable revisit triggers, such as deprecation notices, and review the log on a fixed cadence.

How we help

We write decision records as we design, so the enterprise AI reference architecture we deliver arrives with the reasoning behind every choice and the triggers for revisiting it, ready for your review board and your AI governance and risk process. You keep the records, in your repositories. To set up a decision log for your AI estate or pressure-test the decisions you have already made, talk to an architect.