Claude Code writes beautiful code. It imports the wrong libraries anyway.
It suggests chalk when your team standardized on styleText(). It throws raw errors instead of your logError() helper. It generates perfectly functional API routes that ignore your createRoute() factory pattern. Every PR becomes a archaeological dig, sifting through AI-generated sediment to find where the architecture went off the rails.
The problem isn’t that LLMs are stupid. They’re just context-blind. They can read your files, but they can’t read your mind, or your team’s documented decisions about why things are structured the way they are. Traditional Architecture Decision Records (ADRs) sit in .docs/ like gravestones, honored in the breach while the code evolves in chaos.
But a new approach is changing the game: machine-readable ADRs fed directly to AI agents via Model Context Protocol (MCP) servers. Instead of hoping your AI remembers not to use barrel files, you’re establishing architectural guardrails for AI pipelines that enforce compliance before the first line gets written.
The Governance Gap: When “Working” Isn’t Good Enough
Shadow AI is already rampant in your organization. Developers are prompting LLMs to generate 800-line features, tweaking 20 lines, and merging when CI passes. The code works. It also violates every architectural principle you’ve documented since 2022.
This creates a tension that threatens to collapse under its own weight: the gap between governance on paper and what actually ships. You can mandate that code must be human-readable, commented, and explainable. You can document ownership and accountability. But when an agent generates dependencies and logic at machine speed, human review becomes a bottleneck that teams increasingly bypass.
The result is architectural drift at scale. Each AI-generated PR introduces micro-violations, wrong import patterns, inconsistent error handling, ignored abstraction layers, that compound until your “clean architecture” resembles a Jackson Pollock painting.
Executable Decisions: ADRs That Bite Back
Archgate, an open-source CLI built by Rhuan Barreto, attacks this problem by making ADRs executable. Instead of static markdown files that developers “should” read, Archgate stores decisions as YAML-fronted markdown paired with TypeScript rule files:
// ARCH-003-api-routes.rules.ts
import { defineRules } from "archgate/rules";
export default defineRules((ctx) => [
{
name: "require-createRoute",
severity: "error",
async run() {
const files = await ctx.glob("src/api/**/*.ts");
for (const file of files) {
const hits = await ctx.grep(file, /export\s+default\s+function/);
for (const hit of hits) {
ctx.report({
file,
line: hit.line,
message: "Use createRoute() factory per ARCH-003",
});
}
}
},
},
]);
The archgate check command runs these rules in milliseconds, catching violations with exact file paths and line numbers. Exit code 1 blocks CI merges. It’s implementing traditional build-time architectural enforcement, but with a twist: the rules aren’t just for humans anymore.
The MCP Bridge: Teaching Claude Your Rules
The real innovation is the MCP server. When connected to Claude Code, Archgate exposes tools that let the AI query your architecture decisions before writing code:
review_context: Returns which ADRs apply to files being modified, including the decision text and specific do’s/don’tscheck: Validates Claude’s output against your rules during the conversationlist_adrs: Discovery tool for scanning all decisions up frontadr://{id}: Direct access to full ADR markdown for detailed guidance
The workflow changes fundamentally. Before Archgate, Claude would write code, submit it, and wait for human review to catch violations. Now Claude calls review_context before typing a character, adjusts its approach based on ARCH-001 (command structure) and ARCH-002 (error handling), then validates its own work with check before you see it.
The results are immediate and measurable. Claude stops suggesting new dependencies because there’s an ADR requiring pre-approval. It uses your logError() helper instead of console.error(). It generates command files matching your exact register*Command() pattern. The 3-5 convention violations per PR drop to zero, not because Claude got smarter, but because it finally has access to the context it was missing.
Beyond Static Prompts: Why CLAUDE.md Falls Short
Some developers argue this is overengineering. Can’t you just dump your ADRs into a CLAUDE.md file and call it a day?
The limitation is obvious to anyone who’s tried: CLAUDE.md is a flat file. It doesn’t scale, can’t enforce anything, and gets stale the moment someone forgets to update it. As one developer noted, the file becomes a bloated mess that wastes tokens trying to make Claude comply.
The MCP approach decouples documentation from enforcement. ADRs remain human-readable narratives explaining why decisions were made, while companion .rules.ts files handle the mechanical checking. This separation means:
– Precision: Rules check exact AST patterns, not fuzzy text matching
– Scalability: Domain-specific ADRs load only when relevant files are touched
– Self-improvement: Every violation found during review becomes a new automated rule
It’s the difference between asking someone to “please follow the guidelines” and giving them a linter that fails the build. One relies on memory and goodwill, the other is transitioning from traditional governance to AI readiness.
The Shadow AI Implications
This matters beyond convenience. Shadow AI poses serious risks when agents operate with embedded credentials and delegated access outside standard provisioning. When an AI agent connects to your CRM using a long-lived API key to “automate reporting”, it becomes a non-human identity with persistent access, and zero oversight.
Machine-readable ADRs provide the identity-centric controls needed to govern these agents. By treating architectural rules as executable policies, you create an audit trail for AI behavior. The agent that respects ARCH-004 (no barrel files) and ARCH-006 (dependency approval required) is an agent operating within defined guardrails, not a loose cannon with API access.
The Skeptic’s View: Is This Just Fancy Linting?
Critics on developer forums argue this is elaborate linting dressed up as AI governance. You could, they say, just store rules as files and tell Claude to look at them through skills or chat context.
The counterargument is economic. Anthropic explicitly recommends using scripts and tools to avoid burning tokens on compliance prompts. Without structured MCP tools, you spend compute cycles repeatedly explaining your architecture to an amnesiac assistant. With Archgate, the context is indexed, queryable, and cached. The cost of governance shifts from per-prompt token taxes to a one-time rule definition.
More importantly, deterministic rules catch what LLMs miss. Claude might “know” you prefer styleText(), but under pressure to generate a quick logging utility, it reaches for familiar chalk patterns. The .rules.ts file doesn’t get tired or sloppy. It catches the violation, reports the line number, and blocks the commit.
Dogfooding the Future
Archgate’s own codebase is governed by the ADRs it defines. ARCH-005 enforces testing standards on the test suite. ARCH-002 enforces error handling on the error handler. If the maintainers violate their own rules, archgate check catches it before CI does.
This closes the governance loop: AI agents read decisions, generate compliant code, and violations feed back into improved rules. Over time, compliance increases while enforcement costs decrease, the opposite of traditional governance, where more rules usually mean more meetings.
The implications stretch beyond Claude Code. As AI agents become first-class developers, they need first-class identities and first-class constraints. Machine-readable ADRs provide the scaffolding for defining DDD aggregate boundaries within ADRs that agents actually respect, not just reference.
Your AI agent doesn’t give a damn about your architecture, unless you make it impossible to ignore. Machine-readable ADRs via MCP servers don’t just document your decisions, they enforce them at the speed of AI generation. In a world where code is increasingly written by agents operating in shadows, that’s not just convenience. It’s survival.
