Write ADRs that say when to reopen them

Learning objective

Record decisions in architecture decision records with rejected alternatives, assumptions, and reversal triggers.

Core idea

An architecture decision record (ADR) preserves why a team chose one consequential option under particular constraints. It prevents a successor from mistaking an intentional trade-off for an oversight. For a Claude system, it also prevents a promising evaluation result from becoming an undocumented permission to change models, tools, or human oversight.

AWS’s ADR guidance defines the core as context, decision, and consequences. It treats accepted records as immutable: a subsequent accepted decision supersedes the preceding one. Extend that structure with explicit alternatives, assumptions, and reversal triggers. Those extra sections make the decision reviewable when workloads, dependencies, or organizational priorities change; they are a team convention, not an Anthropic feature.

How it works

Choose a decision worth recording

Write an ADR when a choice changes architectural obligations: where authorization executes, whether a workflow may write without approval, which integration model a team operates, or how an external dependency affects recovery. A minor prompt correction within an agreed design usually belongs in release history, with its evaluation result. A change that removes a human approval step deserves a decision record because it redistributes risk and authority.

Give the record an identifier, a specific title, an owner, a date, and a status. Use a decision log to make the records discoverable. AWS describes Proposed, Accepted, Rejected, and Superseded states; a proposed decision is ready for review, not permission to ship. Record who participated in acceptance and who owns the resulting work.

Make context constrain the answer

State the actual business and technical constraints before the choice: supported tasks, traffic shape, response-time target, permissible effects, integration capabilities, staffing, and uncertainty. Identify which statements are measured and which are assumptions.

For example, “human reviewers can absorb the queue” is an assumption until capacity has been established. “Review takes a median of 45 seconds across 300 sampled cases” is a measurement, with a dataset and conditions that reviewers can inspect. Neither proves that the same capacity holds when case complexity doubles. NIST MAP 1.1 includes assumptions and limitations in documented system context; MAP 1.5 calls for documented organizational risk tolerances.

Link the relevant requirement and release or evaluation revision. Do not paste an entire evaluation report into the ADR. The record should retain the decisive result, its scope, and the reference that lets a reviewer reproduce the comparison. See 4.3.1 for evaluating variants; the ADR records what the team decided from that work.

Preserve serious rejected alternatives

Compare options that a competent architect would actually propose. Include keeping the existing system if that is feasible. For each alternative, record the reason it loses under these constraints, what benefit you forgo, and what condition could make it preferable.

A rejected alternative is not the same as a rejected ADR. One accepted ADR can choose a mediated tool service and reject direct backend access. A rejected ADR records that the team did not accept its proposed decision at all. Keeping these separate prevents a future reader from treating every option in the document as approved.

Avoid categorical claims such as “multi-agent systems are always too slow.” State the measured scope: the evaluated design added two sequential model calls and missed this workflow’s deadline. A later design with independent parallel work may be a different decision. Anthropic’s evaluation guidance calls for specific, measurable, achievable, and relevant criteria; apply those criteria to the comparison rather than declaring a universal winner.

Write the cost you accept

The decision section names the selected option and its scope. The consequences section names both benefits and obligations: additional operating cost, queue ownership, dependency maintenance, failure handling, and migration work. Assign those obligations to roles that can accept them.

An ADR that approves a review queue without a staffed owner records an aspiration. An ADR that approves a lower-cost model without preserving the quality floor leaves builders to resolve the trade-off later. Record residual risk separately from the implementation tasks that reduce it. NIST GOVERN 2.1 supports documented roles, responsibilities, and communication lines; it does not make an architect the sole authority to accept every business risk.

Turn assumptions into review triggers

A reversal trigger states an observable condition, its measurement window, its owner, and the required next action. “Revisit if performance worsens” leaves every part ambiguous. “The service owner opens a replacement proposal if the adjudicated error rate exceeds 2% in either of two weekly 500-case reviews” is actionable. These numbers are an illustrative application rule, not a recommended universal threshold.

Distinguish three responses. A routine review checks whether assumptions remain valid. A reversal trigger opens the architectural decision again. An operational rollback executes an already authorized recovery path; see 6.4.4. A triggered review need not mean immediate reversal, and a critical incident must not wait for the next architecture meeting.

When a replacement decision is accepted, preserve the preceding rationale and mark the preceding record superseded, with a reference to its successor. AWS permits this lifecycle update while keeping the accepted decision’s substance intact. Do not rewrite the original context to make the replacement appear inevitable.

A proposed record is accepted or rejected, and an accepted record is superseded rather than rewritten when a replacement decision is accepted.

Key distinctions and trade-offs

ADR versus architecture description: The description identifies what exists; the ADR explains why one option won. They should refer to the same release and components, but answer different questions.

Assumption versus requirement: An assumption is a proposition whose failure can undermine the decision. A requirement is an obligation the implementation must meet. Calling a mandatory authorization control an assumption can make it seem negotiable.

Reversal trigger versus automatic fallback: A trigger assigns a decision to an owner. It does not silently authorize another model, integration, or data-processing arrangement.

An exhaustive decision log consumes time and buries the consequential choices. Reserve ADRs for decisions whose rationale a successor needs to preserve or challenge. Keep rejected alternatives concise but specific enough to prevent the same debate from restarting without changed conditions.

Architecture / decision scenario

A financial-services firm automates internal policy-answer drafting for 2,000 employees. The team proposes either autonomous publication or publication after reviewer approval. In its illustrative 600-case evaluation, autonomous drafting produces 18 materially unsupported answers. The business owner allows no more than six such answers in that test set, and the operations team can staff 400 reviews per day against a forecast of 250 drafts.

The architect writes an ADR selecting reviewed publication. It records the attractive alternative—lower latency and no review labor—and rejects it because 18 exceeds the accepted six-case ceiling. It also records the capacity assumption, the forecast’s source, and the business owner’s acceptance of the delay and labor cost.

The record assigns the review lead a weekly capacity check. A queue above 350 daily arrivals for two weeks opens a redesign review; it does not remove approval. A candidate configuration meeting the six-case ceiling on the protected evaluation set can also reopen the autonomy decision, with fresh stakeholder approval. If staffing falls short tomorrow, the existing runbook reduces intake rather than treating that emergency as an architectural authorization change.

The platform lead proposes keeping the decision in meeting notes because the team already agrees. The architect rejects that approach: a replacement team would lose the alternatives, assumption owners, and conditions for reconsideration. The ADR preserves all three without prescribing the queue’s implementation details.

Common exam traps

• Recording only the selected technology and omitting the reason alternatives lost.
• Treating an unmeasured assumption as a guaranteed property.
• Rewriting an accepted decision instead of superseding it.
• Giving a reversal threshold without an owner or required action.
• Using a review trigger to bypass an operational safety requirement.

What to remember

Record context, the selected option, serious alternatives, and consequences. Make assumptions testable and give each reversal trigger an owner and action. Preserve decision history so successors can challenge the choice using changed conditions rather than reconstructing a forgotten discussion.

Knowledge check

References

• Amazon Web Services, Architectural decision record process
• NIST, Artificial Intelligence Risk Management Framework (AI RMF 1.0)
• Anthropic, Define success criteria and build evaluations