Architecture decision records (ADRs) capture the reasoning behind significant choices so that future teams understand not only what was decided, but why. A good record is short — typically one to two pages — and is written at the time of the decision.
Template
| Field | Content |
|---|---|
| ID and title | ADR-NNN: a short, specific statement of the decision |
| Status | Proposed · Accepted · Superseded (by ADR-NNN) · Deprecated |
| Date and owner | Date of decision; accountable decision-maker |
| Context | The problem, business drivers, constraints, and relevant facts |
| Decision drivers | The criteria that matter most (e.g., risk, cost, latency, reuse, regulatory obligation) |
| Options considered | Two to four realistic alternatives, including “do nothing” where relevant |
| Decision | The selected option, stated plainly |
| Rationale | Why this option best satisfies the drivers |
| Consequences | Positive and negative effects, new obligations, and risks accepted |
| Reversibility | How difficult the decision is to reverse, and what would trigger reconsideration |
| Principles and standards | Which principles this decision applies or departs from |
| Exceptions | Any approved deviation, its compensating controls, and its expiry date |
| Review date | When the decision should be revisited |
Example: Governed Retrieval for the Meridian Knowledge Assistant
| Field | Content |
|---|---|
| ID and title | ADR-042: Enforce document permissions at retrieval time for the internal knowledge assistant |
| Status | Accepted |
| Context | The assistant retrieves policy and procedure documents from several repositories with different access models. A pilot used a broad service account and relied on prompt instructions to avoid disclosing restricted content. |
| Decision drivers | Prevent unauthorized disclosure; preserve existing access rights; support audit; acceptable latency |
| Options considered | (1) Service account plus prompt instructions; (2) post-generation filtering; (3) permission-aware retrieval using propagated user identity and access-control metadata on indexed content |
| Decision | Option 3 |
| Rationale | Only option 3 prevents restricted content from entering the model context. Options 1 and 2 rely on controls that cannot guarantee non-disclosure. |
| Consequences | Requires synchronized access metadata in the index and identity propagation from the application; adds testing for revoked permissions; slightly higher retrieval latency. |
| Reversibility | Moderate; the index schema and identity integration become shared enterprise patterns. |
| Principles | Security and privacy designed in (A-7); AI is part of the data ecosystem (A-13) |
| Review date | Twelve months, or upon adoption of a new retrieval platform |