Executable Architectural Intent: The Promotion Path From Docs to Constraints

Executable Architectural Intent: The Promotion Path From Docs to Constraints



Tópico: Executable Architectural Intent: The Promotion Path From Docs to Constraints
Categoria: Tutoriais | Programação & Tecnologia
Idioma Principal: Português (Conteúdo de Tecnologia)

Descrição do Conteúdo / Informações:
-------------------------------------------------------------------------
Most project knowledge wants to be findable. A smaller, more important subset has to be binding. Executable architectural intent is the name for that subset — the slice of architectural knowledge that has been promoted out of documentation and into the layer where it can actually constrain what an AI agent does.

Teams writing for AI coding agents accumulate project knowledge fast: ADRs, PRDs, design notes, AGENTS.md files, NotebookLM corpora, Cursor rules, repo-native wikis. Almost all of it is useful, and almost all of it is reference material. It tells the agent what the system is.

A different question sits behind that body of work: which parts of this knowledge are not optional? Which decisions, if the agent ignored them, would make the result wrong even if it ran, passed tests, and looked locally plausible?

That subset has to live somewhere else. It is no longer documentation. It is executable architectural intent.



The operational definition


Executable architectural intent is the slice of project knowledge that has been promoted from documentation into machine-evaluable, enforceable constraints that bind AI agent behavior at generation time.

Three properties distinguish it from ordinary project knowledge:

•
It is binding, not informational. The agent does not have discretion to weigh it against task pressure. A run that violates it is a failed run, regardless of whether the rest of the output looks right.

•
It is machine-evaluable. A hook or a CI gate can produce a deterministic verdict against the resulting artifact. The constraint is not a sentence in a doc; it is something a check can answer with pass or fail.

•
It is traceable. Every verdict can be linked back to the source decision — the ADR, PRD, or policy it derives from — so enforcement is auditable rather than opaque.

Reference knowledge tells the agent what the system is. Executable architectural intent tells the agent what it is not allowed to change about that system while doing the task.



Promotion: from documentation to constraint


Executable architectural intent does not appear by default. It exists because a team explicitly promoted a piece of knowledge from the wiki layer into the governance layer. The shape of that promotion:

An architectural choice is made — usually in an ADR, PRD, design doc, or policy note.

The decision lives in the project wiki or LLM-readable corpus. Agents can read it. Compliance is left to discretion.

The decision is encoded as a scoped, retrievable, enforceable constraint that enters the agent loop and produces deterministic verdicts.

Most architectural knowledge stops at stage two and should. Promotion to stage three is a deliberate act, applied selectively to the rules that genuinely have to bind agent behavior.



The five-criteria bar


The signal that a piece of project knowledge is ready to be promoted is that it meets all five of the following criteria.

•
Explicit. Stated as a checkable rule, not implied across paragraphs of rationale.

•
Scoped. Tied to the part of the system it actually governs, so it is retrieved when relevant and silent when not.

•
Retrievable at the right moment. Surfaced into the agent's context before it commits to a candidate change, not after.

•
Enforceable before code lands. Evaluable by a hook or CI gate that returns a deterministic verdict against the resulting artifact.

•
Auditable back to the source decision. Every verdict can be traced to the ADR, PRD, or policy it derives from, so enforcement is reviewable rather than opaque.

If any one of these is missing, the rule is still doing useful work in the wiki, but it is not yet executable intent. It is documentation that has aspirations.



Why this category exists


Without an explicit name for this layer, teams end up putting binding rules into surfaces that were never designed to enforce them: long CLAUDE.md files, system prompts, prose in ADRs, PR review checklists. Each of those is a useful surface for its own purpose. None of them produces a deterministic verdict at the moment of generation.

The result is a familiar failure mode: the rule was documented, the agent read it, the agent generated code that contradicted it, and the violation was caught (or missed) only in review. The cause was not missing knowledge. It was the absence of an enforcement surface for the knowledge that was already there.

See: Your LLM Wiki Is a Library, Not a Law for the trend-capture version of this argument.



How it differs from adjacent concepts


Layer
What it does
What it does not do

LLM wiki / NotebookLM
Organizes project knowledge for agent retrieval
Cannot return a deterministic verdict at generation time

Prompt files (CLAUDE.md, AGENTS.md)
Reminds the agent what generally matters in the repo
Cannot prevent a session from ignoring or paraphrasing the rule

ADRs & PRDs
Records architectural and product decisions for humans
Cannot, on their own, enforce themselves on a generated artifact

Executable architectural intent
Binds agent behavior at generation and at merge
Does not replace any of the layers above — it sits on top of them

Executable architectural intent is the layer that turns selected pieces of project knowledge into rules the agent cannot route around. It is not a replacement for the wiki or for ADRs. It is the promotion path that some of their contents need to take.



How Mneme implements it


Mneme is the infrastructure layer for executable architectural intent. Architectural decisions are encoded in a version-controlled corpus, retrieved through a deterministic scoping layer before agents generate, and validated at the hook and CI levels after generation. Each verdict carries provenance back to the source decision, so enforcement is reviewable rather than opaque.

The wiki keeps doing its job. ADRs keep doing theirs. Mneme handles the promoted slice: the constraints whose violation would make the run wrong.

Originally published at mnemehq.com.