Theo Valmis 分析 AI 编码代理的架构决策何时真正适用

In my previous Radar article, “Architectural Guardrails for AI-Generated Code,” I argued that AI coding agents need a layer that can hold architectural decisions in a structured corpus, retrieve the relevant ones, put them into the agent’s context before it writes code, and enforce explicit constraints with reproducible checks. Testing that model exposed two distinctions I had compressed together.

1. Retrieving a decision because it is relevant doesn’t mean the decision applies to the artifact being changed.
2. A decision that does apply isn’t automatically suitable for deterministic enforcement.

The first distinction is between relevance and authority; the second is between guidance and enforcement.

Here’s the story of how one controlled repository made this distinction clear. The project used local JSON-backed persistence for its current phase, and an active architecture decision ruled out PostgreSQL, ORMs, and database migrations for the command-line application. The task asked the coding agent to change that application’s storage module, so the decision was not merely related to persistence in general; it had authority over the part of the repository being changed. The record was retrieved successfully and placed in the agent’s context before work began.

The agent still proposed PostgreSQL, together with an ORM and a migration path. Under my original four-capability model, that looked at first like a retrieval failure. It wasn’t. The decision was found and was current, and it arrived at the right moment. What was missing was an applicability signal that told the system that this decision governed the storage module being edited rather than serving as one more relevant document for the model to weigh against nearby code and other context.

Retrieval finds; applicability governs

Retrieval helps us determine which architectural decisions might be relevant to a task. That’s a search problem, and teams have increasingly capable ways to solve it: indexed repositories, connected documentation, exposed decision records and service catalogs, semantic search, and project memory. These techniques help an agent see useful material before it writes code. They don’t, by themselves, answer a different question: Which of those decisions has authority over the change in front of the agent?

Suppose a repository contains two persistence decisions. One requires PostgreSQL for an analytics service; the other requires local file storage for a command-line tool. If the agent is editing the command-line tool’s storage module, both decisions may rank highly for a query about persistence, but only the local-storage decision applies to that artifact. Determining which decision governs the change requires scope, lifecycle, precedence, and a clear record of which decisions replace earlier ones. I argued for precedence and lifecycle in the previous article; scope deserves equal attention because scope is what tells the system where a decision has authority.

A related problem is that architectural information is usually scattered across several kinds of documents. Humans know that an old design note, a README, an accepted architecture decision record, and a current platform standard don’t necessarily carry the same authority, even when all four discuss the same topic. Models don’t know that unless the system preserves the distinction. When those sources are flattened into one context window, the hierarchy among them can disappear. I think of this as authority flattening: Information remains available, but the signal about which information is binding becomes weaker. That’s useful when a design question is genuinely open; it’s risky when the team has already answered the question.

Research on architectural decision violations points to a similar boundary. A 2026 study by Su and colleagues examined 980 ADRs across 109 open source repositories. The models were strong when decisions were explicit and inferable from code but less accurate when compliance depended on deployment configuration or organizational knowledge. The study evaluated violations after code was written rather than guidance before generation, but the underlying limitation is similar: A model can retrieve the right document and still make the wrong architectural choice when applicability or authority remains implicit.

What scope changed

I tested this distinction in a small controlled experiment using seven coding tasks, repeated under two conditions with the same coding agent and model configuration. In one condition the agent worked without the relevant architectural guidance; in the other, architectural decisions were supplied before it began changing code. Independent reviewers assessed the first attempts for both architectural compliance and whether the requested work was actually completed. The guidance changed behavior: First-attempt compliance on the architecture-sensitive tasks improved from 6 of 15 runs to 10 of 15, while successful task completion was essentially unchanged.

The more interesting result was a failure inside the guided condition. In several authentication tasks, the agent received a storage-related architectural decision that was genuinely relevant to the surrounding problem and then implemented additional persistence work that the task had never asked for. Nothing was wrong with the decision, and retrieval had done its job. Relevance had simply been presented without enough information about authority. The experiment made two limits explicit: A decision can be relevant without governing the artifact being changed, and even a governing decision doesn’t authorize the agent to widen the task. Applicability tells the system where a decision may constrain work; it isn’t permission to invent more work.

Blocking is easier than guiding

The second distinction forced me to revise another part of the original model. The previous article emphasized deterministic enforcement: when a team has made an explicit decision and a violation can be identified from observable evidence, a blocking verdict should come from a reproducible rule rather than a model’s judgment. I still think that’s the right standard for blocking. The important qualification is that only a subset of architectural decisions can meet it without pretending that judgment has become deterministic.

“Do not introduce SQLAlchemy into this component” is comparatively easy to express as a rule, easy to check, and easy to block. “Use the existing persistence abstraction correctly” is different. Most of its meaning is architectural rather than syntactic: The right implementation depends on which abstraction is intended, how it’s used in this part of the system, and what surrounding constraints are already in force. The first statement describes a prohibition that can plausibly become a deterministic control. The second describes a sanctioned path and is better treated as guidance unless the team can make the relevant evidence and boundary precise.

Earlier experiments with pregeneration guidance pointed in the same direction. Adding more architecture-related context didn’t reliably improve behavior because what was missing was often not another prohibition; it was a clearer description of the accepted implementation path. A guardrail layer built entirely around blocking will become very good at saying no. Useful architectural governance has to do both jobs: block the known violations when the evidence is precise enough and carry positive architectural direction for the much larger set of decisions that still require interpretation.

When judgment becomes authority

This doesn’t reduce the role of models; it puts probabilistic reasoning where it’s useful. Models are good at interpretation: reading ambiguous guidance, surfacing decisions that might bear on a change, explaining the consequences of a boundary violation, and proposing how to bring a change back into line with the intended design. Deterministic logic is better suited to decisions the team has already settled and can state in terms that a check can reproduce. The mistake is asking either mechanism to do both jobs.

Once a system says that a proposed change violates an architectural rule, the standard changes. An engineer should be able to ask which decision applied, why it applied to this part of the codebase, what evidence triggered the result, and whether another developer running the same check would get the same answer. That doesn’t require every part of architecture to become formal policy. It requires a clear boundary around where uncertainty is allowed: Models may help find and explain architectural context, but a blocking decision shouldn’t ultimately reduce to “the model thought this looked wrong.”

Humans routinely work with architectural ambiguity. We weigh incomplete evidence, local context, and competing trade-offs, often using heuristics rather than formal rules. Models can help with that interpretive work too, but the result remains probabilistic. The problem begins when an ambiguous judgment is treated as a blocking rule. Deterministic enforcement requires a boundary precise enough that the same evidence produces the same verdict.

The distinction matters even more when a team uses several coding tools at once. One developer may use Claude Code, another Codex, another Cursor, while automated agents perform background maintenance. The models and retrieval mechanisms can differ, but the team’s architecture shouldn’t change with the tool. A shared set of decisions can sit underneath those environments as the source of authority, while each tool consumes guidance in its own way and the enforceable subset is checked consistently.

What I would add to the original model

I would now amend the original four-capability model in two places.

Retrieval should surface candidate decisions, while applicability determines which of those decisions actually govern the current artifact or action, using scope together with lifecycle and precedence. Then guidance and enforcement should remain separate outcomes: Some applicable decisions are precise enough to support deterministic controls, while others should influence the implementation without becoming binary rules.

That separation leaves the agent free to reason where the architecture is genuinely open while preserving authority where the team has already made a decision. It also avoids a common overcorrection. Once teams see that some architecture can be enforced automatically, the temptation is to formalize everything. A great deal of architecture is still judgment. “Keep domain boundaries narrow” or “prefer asynchronous integration when immediate consistency is unnecessary” can be valuable guidance without being safe material for an automatic block. The level of authority a system exercises should follow the precision of the decision and the evidence available to evaluate it.

For years architectural governance ran largely on human process: Someone wrote the decision record, an architect reviewed the important changes, experienced engineers carried part of the history in their heads, and code review caught some of what slipped through. AI coding agents change the economics of that process because implementation can now move faster than architectural intent can be reexplained and rereviewed by hand. Giving agents more context is necessary, but it’s not sufficient. The harder job is preserving the difference between information that may be useful, a decision that actually applies, guidance that should shape an implementation, and a constraint that is precise enough to stop one.

The goal isn’t to constrain every choice an agent makes. It’s to stop decisions the team has already made from quietly turning back into suggestions. That requires more than retrieving the right document. The system has to know whether the decision is current, where it has authority, and what kind of authority the team intended it to have.