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.
