ADRs in the Agent Loop: Searchable Architecture Decision History

An architecture decision record should give an agent the reason for a choice before it proposes replacing that choice. We recommend making decision history part of planning and review, with an explicit distinction between a proposed decision and an accepted one. The aim is to let the engineer assess whether the original constraints still apply, rather than treat a retrieved answer as permission to proceed.

Michael Nygard's ADR proposal describes short records for architecturally significant decisions, including context, status, the decision and its consequences. His proposal keeps reversed decisions, marking them as superseded rather than deleting them. That gives us a useful starting point for designing an agent workflow, without assuming that recording a decision proves it remains appropriate.

Record the reason and the rejected options

Use the ADR to explain the constraint that made the choice necessary. Name the affected component, the requirement and the evidence used to compare the options. We suggest recording rejected alternatives explicitly, including the condition under which each might become worth reconsidering. Keep assumptions separate from observations so a future reader knows what still needs checking.

This emphasis on reasoning also has a place in the architecture literature: Bass, Clements and Kazman's fourth edition of Software Architecture in Practice includes a section on documenting the rationale, within its chapter on architecture documentation. For the agent workflow, we recommend linking that rationale to the relevant code change and its acceptance criteria. Do not ask the agent to infer a business constraint from the implementation alone.

Keep the record short enough for the responsible engineer to review alongside the proposed change. Include a stable identifier, title, status, context, decision, rejected options and consequences. Add an owner and links to the supporting evidence where those are needed to establish who can approve the choice. Treat this as a proposed local template, not a universal ADR standard or a requirement to complete every field for every change.

Capture a proposal before approving it

We recommend drafting the ADR while the reasoning is still available in the working discussion. Ask the agent to separate what participants agreed from what it is proposing on their behalf. Where the discussion does not establish an answer, leave an explicit question for the decision owner instead of completing the record with plausible reasoning. Keep the draft in proposed status until the authorised engineer accepts it.

For consequential architectural changes, make the accepted ADR a review requirement before merging the implementation. Define consequential locally, using changes to shared interfaces, data ownership or difficult migrations as candidates. Leave routine formatting choices and easily reversible implementation details in ordinary code review unless they reveal a wider constraint. Do not impose a fixed writing time or promise a particular reduction in discussion time.

If capture is exposed through an agent tool, design the tool to save a proposal and return the saved record's identifier and location. Require the caller to inspect that saved record before treating the write as complete. Keep approval separate from capture, and check that the person approving the decision has authority over its scope. These are design recommendations, not a description of a particular deployed memory service.

Retrieve the record and its current status

For a new task, we suggest searching by the affected component and constraint as well as by the proposed technology. Return the record's identifier, status and source location with any summary. Require the agent to open the full record before relying on a constraint or a rejected alternative. Keep the original document available beside the search index so a reviewer can compare the answer with the recorded reasoning.

Design retrieval to follow replacement links when a match is superseded. Show the older record as historical context, and identify the accepted replacement separately. If the replacement cannot be found, report that gap rather than present the older choice as current policy. Where records disagree about scope, ask the owner to resolve the disagreement before the implementation proceeds.

We recommend treating an ADR as evidence of an accepted intention, not proof of what is running now. Check relevant code, configuration and tests before claiming that the implementation follows it. If the code differs, record the discrepancy and determine whether the implementation needs correcting or the decision needs revisiting. Do not silently rewrite the ADR to match whichever state the agent happened to find.

Supersede decisions without losing their context

Nygard's proposal uses sequential identifiers without reuse and links a superseded decision to its replacement. It also allows status changes, so describing every ADR as wholly immutable would misstate that proposal. We recommend preserving the accepted reasoning while recording status changes and replacement links in version history.

When a constraint changes, ask for a new decision that states what changed and why the previous choice no longer fits. Link the new record back to the old one, then mark the old record as superseded with the replacement identifier. Check both directions after saving, including the status shown by search. Do not accept a retrieval test that finds only the newer title while leaving the older record looking authoritative.

Test the decision workflow

Before relying on the workflow, choose a small set of accepted and superseded records and ask a reviewer to test realistic planning questions. Include a question using different terminology from the record, a missing replacement and a case where the implementation differs from the accepted decision. Check whether the answer identifies the source, respects its status and states what remains unknown. Use the failures to improve the retrieval and approval rules before widening access.

Start with one architectural decision currently under review. Capture its reasoning, obtain explicit acceptance and attach the record to the implementation review. Then ask a separate session to find it and explain when the decision should be reconsidered. Judge the workflow by that inspectable result rather than by how many ADRs it creates.

Update, October 2026

For a later discussion of supplying context before an agent starts work, see What the Agent Does Not Know to Look For. We recommend including relevant accepted ADRs and their replacement links in that initial context, while retaining the checks against current implementation described above.

Sources

• Michael Nygard, Cognitect, "Documenting Architecture Decisions", 15 November 2011
• Len Bass, Paul Clements and Rick Kazman, Addison-Wesley, "Software Architecture in Practice", fourth edition, Chapter 22, section 22.7, 30 June 2021
• Dendro Logic, "What the Agent Does Not Know to Look For", 6 September 2026