{"slug": "executable-architectural-intent-the-promotion-path-from-docs-to-constraints", "title": "Executable Architectural Intent: The Promotion Path From Docs to Constraints", "summary": "Teams are now distinguishing between reference documentation for AI coding agents and a new category called \"executable architectural intent\"—project knowledge that has been promoted into machine-evaluable, enforceable constraints that bind agent behavior at generation time. This subset of architectural knowledge, which tells agents what they are not allowed to change, must meet five specific criteria before it can be promoted from the wiki layer into the governance layer where it produces deterministic verdicts. Without this explicit enforcement surface, teams report a familiar failure mode where documented rules are read by agents but contradicted in generated code, with violations caught only during review.", "body_md": "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.\n\nTeams 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.\n\nA 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?\n\nThat subset has to live somewhere else. It is no longer documentation. It is **executable architectural intent**.\n\n**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.**\n\nThree properties distinguish it from ordinary project knowledge:\n\n**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.\n\nExecutable 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:\n\nAn architectural choice is made — usually in an ADR, PRD, design doc, or policy note.\n\nThe decision lives in the project wiki or LLM-readable corpus. Agents can read it. Compliance is left to discretion.\n\nThe decision is encoded as a scoped, retrievable, enforceable constraint that enters the agent loop and produces deterministic verdicts.\n\nMost 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.\n\nThe signal that a piece of project knowledge is ready to be promoted is that it meets all five of the following criteria.\n\nIf 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.\n\nWithout 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.\n\nThe 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.\n\nSee: [Your LLM Wiki Is a Library, Not a Law](https://mnemehq.com/insights/llm-wiki-library-not-law/) for the trend-capture version of this argument.\n\n| Layer | What it does | What it does not do |\n|---|---|---|\n| LLM wiki / NotebookLM | Organizes project knowledge for agent retrieval | Cannot return a deterministic verdict at generation time |\n| 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 |\n| ADRs & PRDs | Records architectural and product decisions for humans | Cannot, on their own, enforce themselves on a generated artifact |\n| 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 |\n\n**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.\n\nMneme 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](https://mnemehq.com/concepts/enforcement-provenance/) back to the source decision, so enforcement is reviewable rather than opaque.\n\nThe wiki keeps doing its job. ADRs keep doing theirs. Mneme handles the promoted slice: the constraints whose violation would make the run wrong.\n\n*Originally published at mnemehq.com.*", "url": "https://wpnews.pro/news/executable-architectural-intent-the-promotion-path-from-docs-to-constraints", "canonical_source": "https://dev.to/mnemehq/executable-architectural-intent-the-promotion-path-from-docs-to-constraints-22mf", "published_at": "2026-05-29 13:27:21+00:00", "updated_at": "2026-05-29 13:43:14.485207+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-infrastructure", "ai-research", "ai-products"], "entities": [], "alternates": {"html": "https://wpnews.pro/news/executable-architectural-intent-the-promotion-path-from-docs-to-constraints", "markdown": "https://wpnews.pro/news/executable-architectural-intent-the-promotion-path-from-docs-to-constraints.md", "text": "https://wpnews.pro/news/executable-architectural-intent-the-promotion-path-from-docs-to-constraints.txt", "jsonld": "https://wpnews.pro/news/executable-architectural-intent-the-promotion-path-from-docs-to-constraints.jsonld"}}