In a prior Radar piece, Theo Valmis argued that AI coding agents need a layer that stores architectural decisions in a structured corpus, retrieves relevant decisions, injects them into the agent’s context before it writes code, and enforces explicit constraints with reproducible checks. Testing that model revealed two distinct problems that had been compressed together: relevance versus authority, and guidance versus enforcement.
Relevance does not equal authority
Valmis tells the story of a controlled repository where the project used local JSON-backed persistence for its current phase and an active architecture decision excluded PostgreSQL, ORMs, and database migrations from a command-line application. The task asked the coding agent to change that application’s storage module, so the decision was not merely relevant to persistence in general but had authority over the part of the repository being changed. The record was retrieved and placed in the agent’s context, yet the agent proposed PostgreSQL, along with an ORM and a migration plan.
That was not a retrieval failure: the decision was found and current. What was missing was an applicability signal indicating that this decision specifically governed the storage component being edited rather than merely being another relevant document the model could weigh against nearby code and context.
Why scope and preserving authority matter
Retrieval helps surface candidate architectural decisions. Teams now have many tools for this—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, but they do not by themselves answer which of those decisions has authority over the specific change.
For example, a repository might contain two persistence decisions: one requiring PostgreSQL for an analytics service and another requiring local file storage for a command-line tool. If the agent edits the command-line tool’s storage module, both decisions could rank highly for a persistence query, 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 supersede earlier ones.
Architectural information is often scattered across notes, READMEs, accepted architecture decision records (ADRs), and platform standards. Humans understand that these sources carry different authority; models do not, unless the system preserves that distinction. When those sources are flattened into one context window, the hierarchy among them can disappear—an effect Valmis calls authority flattening. That can be acceptable when a design question is open, but risky when the team has already decided.
Supporting evidence from research
A 2026 study by Su and colleagues examined 980 ADRs across 109 open source repositories. The models performed well when decisions were explicit and inferable from code, but were less accurate when compliance depended on deployment configuration or organizational knowledge. The study evaluated violations after code was written rather than guidance before generation, yet it highlights a similar limitation: a model can retrieve the right document and still make the wrong architectural choice when applicability or authority remain implicit.
Experimental findings: applicability matters
Valmis ran a small controlled experiment with seven coding tasks, repeating each under two conditions using the same 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 editing code. Independent reviewers assessed the first attempts for architectural compliance and whether the requested work was completed.
The guidance changed behavior: first-attempt compliance on architecture-sensitive tasks improved from 6 of 15 runs to 10 of 15, while successful task completion was essentially unchanged. The more interesting failure occurred inside the guided condition: in several authentication tasks the agent received a storage-related architectural decision that was genuinely relevant to the surrounding problem, then implemented additional persistence work the task had never asked for. Retrieval had worked, but relevance was presented without sufficient 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
Valmis revises part of his earlier model around deterministic enforcement. He continues to assert that 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. The crucial qualification is that only a subset of architectural decisions can be expressed and checked deterministically without pretending that judgment has become deterministic.
Compare two statements:
- “Do not introduce SQLAlchemy into this component” — relatively easy to express as a rule, easy to check, and easy to block.
- “Use the existing persistence abstraction correctly” — mostly architectural rather than syntactic: correct 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. This is better treated as guidance unless the team makes the relevant evidence and boundary precise.
Past experiments with pregeneration guidance showed similar results: adding more architecture-related context did not reliably improve behavior because what was missing was often not another prohibition but a clearer description of the accepted implementation path. A guardrail layer that only blocks will become very good at saying no. Useful architectural governance needs both: block known violations when the evidence is precise, and carry positive architectural direction for the larger set of decisions that still require interpretation.
When probabilistic judgment is the authority
This does not diminish models’ role; it puts probabilistic reasoning where it is 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 fits decisions the team has already settled and can state in reproducible terms. The mistake is asking either mechanism to do both jobs.
Once a system says 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 does not require every part of architecture to become formal policy, but it does require a clear boundary around where uncertainty is allowed: models may find and explain architectural context, but a blocking decision should not reduce to “the model thought this looked wrong.”
Humans routinely operate with architectural ambiguity, weighing incomplete evidence, local context, and competing trade-offs using heuristics rather than formal rules. Models can assist with that interpretive work, but the result remains probabilistic. The problem arises 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.
Multiple tools, single source of authority
This distinction is more important when a team uses several coding tools concurrently: one developer may use Claude Code, another Codex, another Cursor, while automated agents perform background maintenance. Models and retrieval mechanisms may differ, but the team’s architecture should not 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.
Proposed amendment to the original model
Valmis proposes two amendments to his original four-capability model:
- Retrieval should surface candidate decisions, while applicability should determine which of those decisions actually govern the current artifact or action, using scope together with lifecycle and precedence.
- Guidance and enforcement should remain separate outcomes: some applicable decisions are precise enough to support deterministic controls, while others should influence implementation without becoming binary rules.
This separation lets the agent reason where the architecture is genuinely open while preserving authority where the team has already decided. It also avoids overformalizing everything: many architectural principles are valuable guidance but unsafe as automatic blocks. The level of authority a system exercises should follow the precision of the decision and the evidence available to evaluate it.
Conclusion
For years, architectural governance ran on human process: someone wrote the decision record, an architect reviewed important changes, experienced engineers carried history in their heads, and code review caught some issues. 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 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 precise enough to stop one. The system must know whether a decision is current, where it has authority, and what kind of authority the team intended it to have.
