dooopSoftware · Process · 14 min

How to Record Architecture Decisions for AI Use

Learn how to create ADRs useful for AI, with context, alternatives, consequences and review criteria that guide people and agents.

Published on September 6, 2026

CENTRAL THESIS

An ADR is not a meeting minute. It is recoverable context to review AI-assisted changes without repeating old decisions.

Useful records separate constraint, alternative and consequence. This way, people and agents know when to reopen the decision.

Months after an architectural choice, the team can return to the same point without realizing: why does this integration exist, which alternatives were discarded and what consequence was accepted?

When an AI suggests a change, the problem is rarely just syntax or local testing. The greater risk is that it responds well to a small task but poorly to the system design. A good record reduces this ambiguity for people and agents.

The recording criterion is this: when someone, human or agent, will change the system sometime later, the essential information must be recoverable to avoid repeating an old discussion as if it were a new discovery.

This question changes the role of the architecture decision record, also known as ADR. It ceases to be a compliance document and becomes a small unit of context. Small enough to be read during a review. Independent enough to survive outside the memory of those who participated in the choice. Testable enough to guide a concrete change.

This care affects AI adoption in the engineering process. If the organization is structuring a business-connected artificial intelligence strategy, technical documentation cannot be treated as dead archive. It becomes part of the environment where AI-assisted decisions are made, reviewed and corrected.

Record Decisions That Limit Future Changes

Not every technical decision deserves an ADR. If the team records every local preference, the repository becomes a cemetery of documents nobody consults. The criterion should be consequence, not preference.

An architecture decision must be recorded when it creates limits for future changes. This includes choices that affect more than one module, define integration patterns, create operational dependencies, impose relevant exceptions or make a change technically possible but undesirable in the current design.

Some signals help:

The choice affects more than one team, service or domain.
A technically viable alternative was rejected for an architectural reason.
The change requires a pattern that must be repeated in other parts of the system.
An exception was accepted and may look like an error to newcomers.
A test, contract or verification protects the decision.
The decision should be reopened if a specific condition changes.

The point is not to document everything. It is to document what creates boundaries.

DORA recommends working with small, independent and testable units to get feedback on changes and review hypotheses earlier. The same guidance warns about the difficulty of reviewing and integrating large AI-generated changes in an engineering flow DORA. A useful ADR follows the same logic: it must be small, independent and reviewable.

When the record becomes a chore, it hinders. When it becomes a loose sentence, it does not guide. The right format is in the middle: enough context to decide, little narrative and explicit consequence.

Context for AI Needs to Separate Constraint from Circumstance

Anthropic defines context engineering as selecting and maintaining the information available to the model during inference. This set includes instructions, tools, external data and history, within a limited window Anthropic. In other words, context is not everything that exists. It is what is on the table at the moment the AI will respond.

Therefore, an ADR needs to distinguish persistent information from transient information.

Persistent information is that which remains relevant for future changes: domain boundaries, critical dependencies, consistency requirements, communication patterns, isolation rules, operational security assumptions, observability constraints or compatibility with existing components.

Transient information is momentary pressure: delivery deadline, availability of a person, a temporary infrastructure constraint or a decision made to unblock a specific step. They may enter the record but should not appear as permanent foundation.

A good context field answers:

What problem was being solved?
Which constraints truly limited the choice?
Which part of the system is affected?
Which condition was temporary and should not be confused with an architectural rule?

This care avoids a common error in AI-assisted flows: the agent finds an old decision but does not know if it still represents a system constraint or just a historical shortcut. If the team does not separate the two, the tool may preserve what should be reviewed or propose breaking what should be protected.

For teams maturing AI use, this distinction also connects to capability diagnosis. An AI maturity diagnosis should not look only at available tools but at the quality of the context that supports decisions and reviews.

Alternatives Must Be Recorded Without Freezing the Discussion

Recording alternatives does not mean reopening the debate every time someone reads the ADR. It means explaining why a plausible option was not chosen.

This is especially relevant for architecture and AI decisions. A code agent may suggest a technically correct solution because it is common, simple or well represented in public examples. But the real system may have rejected that solution because of coupling, consistency, latency, operation, team dependencies or cost of change.

The record should describe alternatives with three elements:

What was considered.
Why it was discarded in that context.
Under what condition it could be reconsidered.

The third part is what separates living architecture from dogma. A decision does not need to be eternal to be respected. It needs to say when it should be reopened.

For example, instead of writing only “do not use synchronous calls between these services,” the ADR can record: “direct synchronous calls were discarded because they would increase coupling between the order flow and the billing service. They may be reevaluated if the operational dependency between services changes and if there is an explicit degradation criterion for billing failure.”

This takes effort but avoids unproductive review. The reviewer does not need to say only “we already discussed this.” They can point out: “the suggestion repeats a discarded alternative and does not present the new condition that would justify reopening the decision.”

This is the kind of phrase that transforms oral memory into operational criteria.

Architectural Consequence Must Become a Review Criterion

The weakest part of many decision records is the consequence. The team writes the adopted option, lists a generic justification and moves on. Months later, no one knows what cost was consciously accepted.

Every architecture decision buys something and pays with something else. It may facilitate evolution of a module and hinder flow tracking. It may reduce coupling and increase eventual latency. It may simplify operation and limit domain autonomy. It may make code more explicit and increase repetition.

If the consequence does not appear, human review is stuck on local code functioning. The reviewer asks if it passed the test, if it compiles, if it follows style. But stops asking if the change preserves the chosen design.

A useful ADR turns consequence into review questions:

What does this decision make easier?
What does it make harder?
What risk did the team accept?
What type of coupling now exists?
What test or verification protects the choice?
What change would require more careful human review?

GitHub’s documentation on Copilot agents describes features with distinct environments and permissions and emphasizes human supervision and output review GitHub. The point here is not to transfer decision to the tool. It is to design a flow in which human review can see what the tool may have ignored.

This is the point where the ADR becomes a review criterion.

If an AI-assisted change contradicts an assumed consequence, the problem is not just “the agent was wrong.” It can be one of three things: the change is misaligned, the ADR is incomplete or the old decision needs to be reopened. Each requires a different action.

A Minimal Format for ADRs Usable by People and Agents

The value of an ADR is not in size. It is in decision precision. A minimal format may work better than an extensive model, as long as it captures points that guide future changes.

A concise record may contain:

Title: written with affected domain, module or pattern.
Status: proposed, accepted, replaced or reopened.
Date: the actual decision date in the repository.
Context: problem, persistent constraints and relevant transient circumstances.
Decision: the adopted option, written as a concrete choice.
Alternatives: considered options, reason for discard and return condition.
Consequences: accepted costs, assumed risks and expected behavior.
Verification: test, review rule, contract or evidence that protects the decision.
Reopening signals: conditions that justify changing the decision.
Internal links: related files, modules, pull requests or documents in the repository.

The title deserves attention. For a person, it helps find the document. For an agent, it helps recover the right context when the task mentions a module, domain or pattern. A title like “Asynchronous communication in order confirmation flow” is better than “ADR 014.” The identifier may exist but should not carry meaning alone.

The verification field is also decisive. If there is no automated test, there may be an explicit review criterion. DORA describes continuous integration as frequent integration into the main code, accompanied by build and automated tests. Fixing a broken build should have priority over new changes DORA. The ADR does not replace this flow but can say what kind of test or verification needs to exist to protect the choice.

For those organizing an AI roadmap, this point is usually less flashy than choosing tools. Still, it weighs on the ability to use AI without relying on informal memory at every change.

Minimum Criteria to Record an Architecture Decision Usable by AI

Use these criteria before considering an ADR ready to guide people and agents:

Context: does the record explain what problem was being solved and which constraints were relevant at the time of choice? Acceptance sign: a person or agent can distinguish the reason for the decision from a generic technical preference.
Alternatives: does the record present at least one considered alternative and why it was discarded? Acceptance sign: a next code suggestion repeating the rejected alternative must bring a new condition.
Decision: is the adopted option written as a concrete choice, not an abstract principle? Acceptance sign: it is possible to point in the code which changes obey or violate the decision.
Consequences: does the record declare the accepted cost, assumed risk and expected system behavior after the choice? Acceptance sign: the review can evaluate not only if the code works but if it preserves the chosen design.
Test or verification: is there any test, automated verification or review criterion associated with the decision? Acceptance sign: the decision does not depend only on oral memory to be protected.
Reopening: does the record say under which conditions the decision should be reviewed? Acceptance sign: the team knows when to change their mind without treating every change as architectural break.
AI retrieval: do the title, terms and internal links help the record appear in the context of a related task? Acceptance sign: an agent or developer can find the decision from the affected module, domain or pattern.

This checklist does not prove the architecture is good. It only tests if the choice was written so it can be recovered, discussed and reviewed.

How to Use the ADR in AI-Assisted Change Review

The ADR needs to enter the review flow, not remain isolated in a folder that only appears in retrospectives. When an AI-assisted change touches a module with a recorded decision, the reviewer should ask four questions.

First: does the change respect the decision context? If the ADR states the module should not depend directly on another service, the review must check if the suggestion created that dependency for convenience.

Second: does the change contradict any assumed consequence? If the architecture accepted eventual latency in exchange for lower coupling, a change trying to simulate immediate consistency may be undoing the decision without declaring it.

Third: did the AI introduce an implicit alternative? Sometimes the code does not say “let’s change the architecture,” but creates a new pattern that competes with the previous one.

Fourth: does the change require a new ADR or reopening the previous one? Not every divergence is an error. Sometimes the context changed. The problem is changing without naming the change.

This design makes the review more explicit. Not because AI will always obey, but because the team can review with visible criteria.

Fictional Example: Service Communication in an Order Flow

Consider a fictional example. A team maintains an order system and a billing service. When implementing order confirmation, an agent suggests a direct synchronous call: when the order is confirmed, the order service calls the billing service and waits for the response.

The solution seems simple. It passes local module tests. The code is readable. But there is an ADR accepted by the team for that flow.

The record states that communication between orders and billing, in this specific case, must be asynchronous. The context: the order flow needs to remain available even when billing is temporarily unavailable. The persistent constraint: orders and billing have different operational rhythms. The transient circumstance: there was pressure to simplify the first delivery, but it should not become a permanent justification.

The discarded alternative was direct synchronous call. The reason: it would increase operational coupling between services and make billing unavailability block order confirmation. The alternative could be reopened if the product required billing confirmation before accepting the order and if the degradation design was defined.

The adopted decision was to publish an order confirmed event and allow billing to process this event asynchronously. Accepted consequences were eventual latency, need for idempotency in the consumer and greater attention to flow observability. Associated verification includes tests to avoid duplicate processing of the same event and careful human review when a change tries to introduce direct dependency between services.

In this fictional scenario, reviewing the AI suggestion does not need to depend on preference. The reviewer can say: “the change proposes an already discarded alternative and does not present a new condition to reopen the ADR.” They can also request a more precise change: “keep event publication, preserve idempotency and update the test that protects against duplication.”

Expected effects of this practice would be hypotheses to measure, not presumed results. The team could observe if fewer suggestions repeat discarded alternatives, if reviews become more objective and if architectural changes start to be explicitly reopened. But this must be monitored in the real flow, not declared as automatic benefit.

The Limit: ADR Does Not Save Bad Architecture Nor Replace Judgment

A bad ADR can give the appearance of rigor to a weak choice. Recording a decision does not make it correct. Nor does it transfer authority to AI to reinterpret old architecture.

AI can retrieve, compare and suggest. It can help locate documents, summarize consequences and point out possible conflicts. But when a change alters architectural direction, human review remains part of process design. Not as late correction. As deliberate decision about risk, cost and evolution.

It is also worth recognizing that some decisions do not need to become ADRs. Local preferences, reversible adjustments and changes without architectural consequence can remain in the pull request or module documentation. Forcing formality where there is no impact creates noise and reduces adherence.

Next week, choose a module with frequent changes, identify an architectural decision that limits future changes and record it in minimal format: context, alternative, decision, consequence, verification and reopening. Then use this history to explicitly reopen decisions when context changes.

If you want to discuss this decision in the context of your company, talk to dooop.

Sources

NEXT DECISION

Discuss Application in Your Company

Conversation about the software company context

Content from dooop. Registration allows relating this topic to the reader’s journey and tracking interest in the theme.