Tools

Who Explains an AI Agent's Code Decisions?

ADRs for AI records Agent recommendations, reasoning, confidence, and falsification criteria in Git. The approach supplies decision context that code diffs cannot capture, but teams must anchor it in evidence to avoid turning ADRs into formalities.

Font size

An AI Agent can modify a dozen files in one run, but once the work is committed, usually only a commit message and a diff remain. Those artifacts show what changed, but they rarely answer: Why was this approach chosen? Where did the model feel uncertain? Would a fresh run produce the same result?

Git preserves facts about code, not the full reasoning behind a decision. ADRs for AI aims to fill that gap by recording a model's decision basis in Git and using ORRCF to require Agents to surface uncertainty.

The Missing Layer Is Decision Context, Not Code

Suppose an Agent is asked to replace a synchronous task with an asynchronous queue.

The final diff may contain only a few lines: a new producer, consumer, and retry policy, followed by the removal of the old blocking call.

Code review can catch race conditions, message loss, and duplicate consumption. But reviewers cannot see the full chain of reasoning:

  • Why Redis Streams instead of Kafka?
  • Why keep the existing database as the source of truth?
  • Were task latency and operational complexity evaluated?
  • What symptoms would indicate that this choice was wrong?

Once an Agent is involved, these questions are more likely to collapse into a single line: “Optimized according to best practices.”

Conventional ADRs were designed for questions of this kind. They are lightweight decision records. Nygard's classic format typically covers context, options, decision, and consequences. A team records why it selected a particular technical path, allowing people who were not present for the discussion to understand why the code took its current shape.

ADRs for AI makes two changes.

First, it extends ADRs to human-AI collaboration. An AI Agent can author a decision proposal and later read records of subsequent decisions.

Second, it stores these Architectural Deliberation Records in Git. The records no longer disappear with a chat window. They enter version control and can be reviewed, committed, and rolled back alongside the code.

A natural-language explanation confined to a chat window is little more than a log. Once it lives in Git, it can become collaborative engineering context.

ORRCF: Five Deliverables Before the Model Proceeds

ADRs for AI uses ORRCF to organize the decision proposals produced by a model:

  1. Options: Which viable choices exist, including keeping the current state?
  2. Recommendation: Which option does the model recommend?
  3. Rationale: Why does it recommend that option, and what does it give up?
  4. Confidence: How confident is the model in its recommendation?
  5. Falsifier: What evidence would show that the recommendation is invalid?

It looks like an explanation template, but its purpose goes beyond making the output more complete.

ORRCF requires the model to expose uncertainty and submit its recommendation for human approval or override. The model cannot commit code with nothing but a polite summary attached. It must first deliver a decision proposal that can be reviewed.

For example, a proposal for an asynchronous queue task might look like this:

## Options

1. 保留同步调用
2. 使用 Redis Streams
3. 使用 Kafka

## Recommendation

使用 Redis Streams。

## Rationale

当前吞吐量不需要 Kafka 的分区和运维成本。
Redis Streams 已提供 consumer group、确认机制和消息保留。

## Confidence

中高。主要不确定性是现有重试逻辑迁移后的幂等性。

## Falsifier

如果压测中 consumer lag 持续增长,或重投导致重复处理,
则当前方案不成立,应重新评估 Kafka。

Humans can approve the recommendation or override it. The reason for an override can also be recorded in the ADR. The next Agent can then read not only the code, but also the trade-offs the team has already made.

This creates a sustainable scaffolding for AI-assisted programming. It preserves both the model's recommendation and the team's modifications to it. Later tasks can treat approved, rejected, and conditional proposals as context.

This does not mean every commit needs a long-form document. It is better suited to high-risk, high-cost, or otherwise difficult-to-under-from-the-diff changes that benefit from an additional decision check.

ADRs in Git Become Collaborative Context

Many Agent tools are already good at retrieving code. They locate relevant files, read symbol definitions, search for callers, and then modify the implementation.

ADRs add another layer of retrieval: which choices have already been discussed, and which edge cases have already caused trouble.

Suppose a team selected SQLite during its first database migration because traffic was low. As traffic changed, it later switched to PostgreSQL. The ADRs should contain two records:

  • Why SQLite was selected initially.
  • Why the team later migrated to PostgreSQL.
  • Which assumptions had become invalid.
  • Which constraints remained in place.

An Agent that reads only the current code may mistake the old approach for an accidental implementation. An Agent that reads the ADR has at least a chance of seeing the constraints that shaped it.

Git also introduces three collaboration benefits.

First, decisions and implementations can be reviewed together. Reviewers can compare the code with the proposal and check whether the model delivered on its commitments.

Second, decisions can be rolled back. If the code was wrong, the diff can be reverted. If the architectural choice was wrong, a new ADR can explicitly supersede it without erasing the history.

Third, ownership boundaries become clearer. Humans approve or override an explicit proposal rather than assume responsibility for an outcome hidden behind a vague claim that “the model handled it.”

ADRs should not, however, replace testing, code review, or architectural discussion. They simply give those activities another shared point of reference.

Counterpoint: More Records Do Not Necessarily Mean More Oversight

Adding a structured format to an Agent workflow makes it easy to produce a polished-looking result: every task now includes Options, Rationale, Confidence, and Falsifier.

It may also be pure formalism.

Confidence is unreliable. A model that reports “0.8” does not imply an 80% probability that the result is correct. Phrasing habits in training data, prompt templates, and even task difficulty can alter the number. At best, it is a signal that needs an explanation.

A Falsifier is not a test either.

If a model writes, “If consumer lag keeps growing, the approach has failed,” that does not mean it has written a load test or that the team knows the growth threshold. A falsification condition that will never be executed merely restates uncertainty in a more formal register.

ADR quality must therefore be grounded in engineering evidence:

  • Does the Rationale cite real constraints rather than generic best practices?
  • Does the Recommendation match the actual code change?
  • Does the Falsifier correspond to an executable test or monitoring metric?
  • When a human overrides the model, is the reason for doing so recorded?
  • Do subsequent Agents actually read and use historical ADRs?

There is also a subtler problem: records can create an illusion of oversight.

The more complete the documentation, the more likely reviewers are to assume the decision has been handled properly. But if ORRCF is an automatically generated template applied at the end of a task, it may merely restate the code rather than explain it.

A genuinely useful ADR should make it possible for people to discover inconsistencies.

For example, a model might recommend Redis to avoid database lock contention, while the actual code updates a state table inside a transaction. A reviewer can immediately see the gap between the proposal and the implementation.

That is more valuable than a model confidently stating that it completed the task.

ADRs for AI is therefore better understood as an audit interface than a quality-assurance interface. It makes AI recommendations easier to inspect, but it does not automatically make those recommendations correct.

The original project description comes from the ADRs for AI project website and its Hacker News discussion. The project demonstrates Architectural Deliberation Records, the five-part ORRCF format, a mechanism for human approval or override, and a sustainable Git-based scaffolding for AI-assisted programming.

Editorial Perspective

The value of ADRs for AI lies not in documenting AI, but in turning model recommendations into auditable engineering artifacts. Code describes what the system is now; an ADR explains why it became that way. Once both share the same Git history, later engineers and Agents have a chance to inherit the decision context.

ORRCF's immediate value appears to be in the review interface rather than in autonomy. It may not make Agents smarter, but it can expose deviations earlier: the recommendation does not match the code, the falsification condition has no corresponding test, or a human override lacks a recorded rationale. Teams that treat it as nothing more than automated meeting minutes will quickly turn it into a documentation burden.

That differs from earlier AI programming tools, which primarily focused on code completion and test generation. Agents now make changes across files, giving them a much broader decision scope. The material provides no evidence about production performance, project scale, or changes in error rates, so its maturity remains unproven. The test is not how polished the ADRs look, but whether a new Agent can avoid repeating an old mistake six months later.

Source: https://adrs.systems