Artificer Digital The Artificer's Grimoire

Scout: Declarative Architecture — Encoding Guardrails for Coding Agents

Summary

Three independent signals — Teleport’s finding that over-permissioned AI systems suffer 4.5x more security incidents, the ALARA paper’s structural enforcement of least-privilege agent context, and InfoQ’s Declarative Architecture proposal for machine-enforceable ADRs — converge on a single thesis: the most important architecture documentation you write today is no longer primarily for humans, it is for coding agents, and it must be machine-enforceable rather than merely machine-readable. The practice of encoding architectural constraints as agent guardrails is rapidly crystallizing into three distinct enforcement layers: structural tool-access restrictions that make violations impossible, CI/CD-integrated fitness functions that catch violations at build time, and in-context specification files (CLAUDE.md, AGENTS.md, architecture.md) that guide agent reasoning. The gap between theory and practice remains significant — most teams today rely exclusively on the weakest layer (prose instructions in context files) while the tooling for the strongest layer (structural enforcement) is just reaching production readiness. The practitioners who close this gap first will capture the productivity benefits of agentic coding without the 4.5x incident multiplier.

Key Findings

1. The Permission-Incident Multiplier Is Now Quantified

Teleport’s “2026 State of AI in Enterprise Infrastructure Security” report, based on 205 interviews with CISOs and security architects at organizations with 500-10,000 employees, provides the first large-scale empirical evidence that AI agent permissions directly predict security outcomes [1]. The headline number — organizations granting excessive AI permissions experience a 76% incident rate versus 17% for those with restricted permissions — makes the abstract principle of least privilege concrete and financially quantifiable.

The report reveals a troubling readiness gap: 79% of enterprises are evaluating or deploying autonomous AI systems, but only 13% feel adequately prepared for security implications. 43% have no formal AI governance controls whatsoever. The 67% still using static credentials for AI systems face 20% higher incident rates. Only 3% have implemented automated machine-speed governance controls — meaning 97% of enterprises are governing AI systems at human speed while the systems operate at machine speed.

This data reframes architectural guardrails from a quality concern to a security imperative. The question is no longer whether to constrain agent permissions but how to do so without destroying the productivity gains that motivated adoption.

2. Declarative Architecture: From ADRs to Machine-Enforceable Intent

The InfoQ article “Architectural Governance at AI Speed” by the Adaptech Group proposes the most comprehensive framework for transforming architectural decisions into automated guardrails [2]. The core definition: Declarative Architecture is “the practice of distilling architectural decisions and constraints into machine-enforceable declarations of intent that enable safe independent action.”

The article identifies three concrete implementation patterns:

Pattern A: Event Models as Declarations. Event Modeling produces eventmodel.json files backed by formal schemas that decompose architecture into vertical slices. Each slice provides a bounded specification that agents can implement and verify against Given-When-Then criteria. The “Ralph Loop” pattern shows how AI agents iterate on individual slices until specifications pass, accumulating organizational knowledge from each iteration. The key insight: “Spec + Vertical Slice = Candy for AI” — bounded scope with clear acceptance criteria is where agents perform best.

Pattern B: OpenAPI Validators as Guardrails. Central platform teams define validation rules (path conventions, versioning, error structures) enforced across CI/CD pipelines. This shifts validation left into IDEs and pull requests while blocking non-compliant deployments. The validation pipeline produces telemetry — violation rates, lead times, developer feedback — enabling continuous refinement. The article’s claim that “alignment becomes observable” is significant: it means architectural decisions become measurable, not just enforceable.

Pattern C: architecture.md as Executable Manifest. This is the most directly actionable pattern. Teams reduce each ADR to an atomic directive with enforcement severity:

* [ADR-088] [Warn] Require asynchronous Kafka events for inter-service communication
* [ADR-004] [Block] Services must own their data
* [ADR-067] [Warn] Log messages must use structured JSON

Governance agents can compare this manifest nightly against the central ADR corpus, opening PRs for updates. During code review, agents fetch only the relevant clauses — loading data rules only when schemas change, communication rules only when new endpoints appear. The article envisions the same file seeding fitness functions, validating infrastructure identity, and guiding agent code review.

The critical principle from the article: “A declaration that can only be understood by a human still depends on that human being in the loop. Only a declaration that machines can reason over can scale governance beyond the bandwidth of any individual or review board.”

3. ALARA: Structural Enforcement Beats Interpretive Compliance

The ALARA paper (Agostino & D’Souza, arXiv 2603.20380) introduces a framework that makes the strongest case for structural rather than interpretive enforcement of agent constraints [3]. Borrowing from radiation safety’s ALARA principle (As Low As Reasonably Achievable), the paper proposes a declarative Context-Agent-Tool (CAT) data layer implemented through the open-source npcsh shell.

The CAT architecture uses three interlocking file types:

  • Context files define team-level configuration, designating orchestrators and sub-team hierarchies, restricting visibility to appropriate scopes.
  • NPC files define individual agents through name, directive, model specification, and a Jinx list (tool catalog that simultaneously functions as a permission boundary).
  • Jinxes (Jinja Execution templates) specify tools as executable YAML definitions with typed inputs, sequential execution steps, and Jinja-templated code.

The critical innovation: “tools not present in an agent’s schema cannot be invoked” regardless of prompt content. This is structural enforcement — the system parses and enforces these files at the infrastructure level. If a tool is not in the agent’s Jinx list, the model never sees it and cannot call it. This eliminates an entire class of prompt injection attacks: you cannot trick an agent into using a tool it does not have.

The evaluation across 22 locally-hosted models (0.6B to 35B parameters) on 115 tasks reveals that models trained for tool-use achieve performance at 4B parameters that untrained models fail to reach at 27B. Tool-use capability is a distinct, trainable skill. This has implications for guardrail design: the right constraints can make smaller, cheaper models perform reliably, while broad permissions on larger models create larger blast radii.

The paper’s autonomy spectrum — from narrow Jinx lists with no delegation to broad catalogs with delegation capability — is controlled by editing a single YAML list. This operationalizes the principle that high automation and high user control are independently achievable.

4. The Enforcement Spectrum: Three Layers of Decreasing Strength

Synthesizing across all sources, architectural guardrails for coding agents fall on a spectrum from strongest to weakest enforcement:

Layer 1 — Structural Enforcement (Impossible to violate). The agent literally cannot perform the restricted action because the capability is not available. The ALARA/npcsh approach exemplifies this: tools not in the Jinx list do not exist in the agent’s world. Stripe’s Toolshed (from Edition 4 coverage) operates similarly — each Minion gets a curated slice of 500 tools, not the full catalog. AgentGuard’s .UseAgentGuard() middleware intercepts tool calls and blocks SQL injection, path traversal, SSRF, and command injection before they execute [7]. This is the gold standard but requires framework-level integration.

Layer 2 — CI/CD Enforcement (Caught before merge). Fitness functions, linters, and validators run in the build pipeline and block merges on violation. ArchUnit (Java), PyTestArch (Python), ArchUnitTS (TypeScript), and the new Archgate CLI all operate at this layer [8][9][10]. Spectral and Vacuum lint OpenAPI specifications against custom rules. The InfoQ article’s OpenAPI validator pattern sits here. This layer is well-established for human developers and extends naturally to agent-generated code — the agent’s PR goes through the same pipeline. The weakness: violations are caught after code is written, wasting agent compute and review cycles.

Layer 3 — In-Context Guidance (Relies on model compliance). CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, and architecture.md files provide natural-language instructions that agents read and (usually) follow. Over 60,000 open-source projects now use AGENTS.md [15]. This is the most widely adopted layer and the easiest to implement — but it is the weakest because compliance depends on the model’s attention, context window utilization, and instruction-following fidelity. Research suggests frontier LLMs can reliably follow around 150-200 instructions, and system prompts consume roughly 50 of those [5]. Prose-based constraints are suggestions, not guarantees.

The practical implication: a mature guardrail strategy uses all three layers in combination. Structural enforcement for catastrophic-risk actions (data deletion, production deployment, credential access). CI/CD enforcement for architectural consistency (dependency rules, API contracts, naming conventions). In-context guidance for design intent and coding style.

5. Archgate: The First Purpose-Built ADR Enforcement Tool

The Archgate CLI (github.com/archgate/cli) represents the most direct attempt to bridge the gap between ADRs and executable enforcement [8]. Its tagline: “Enforce Architecture Decision Records as executable rules — for both humans and AI agents.”

The architecture pairs each ADR markdown file with a companion TypeScript rule file:

.archgate/adrs/
  ARCH-001-command-structure.md
  ARCH-001-command-structure.rules.ts
  ARCH-002-error-handling.md
  ARCH-002-error-handling.rules.ts

archgate check validates the codebase against all rules, reporting violations with file, line number, and ADR reference. Exit code 1 blocks CI merges. Pre-commit hooks enforce locally. The tool integrates with Claude Code and Cursor via editor plugins, enabling agents to read ADRs before generating code and validate changes against rules before submitting.

This is notably the first tool to close the full loop: ADR documentation, automated enforcement, CI integration, and agent-aware editor plugins in a single system. The 46 releases and Apache-2.0 license suggest active development, though the project is still early-stage.

6. ADR-as-Code-Review: Making Agents Enforce Architecture During Review

Shing Lyu’s demonstration of ADR-powered code review with GitHub Copilot shows the pattern working in practice today [11]. The approach stores ADRs in docs/adr/ and configures .github/copilot-instructions.md to instruct the Copilot reviewer to cross-reference all code changes against documented decisions.

The results are striking: when a developer attempted to change Author IDs from number to string, Copilot flagged the violation seven times with specific ADR citations. More importantly, when the developer explicitly instructed the coding agent to violate ADR-0003 (business logic in service layer), the agent refused and explained: “Moving business logic into the controller would violate ADR-0003” — suggesting the human update the ADR first if the architectural change was truly needed.

This demonstrates an underappreciated dynamic: well-documented ADRs in the repository create resistance to architectural drift that applies to both humans and agents. The documented architecture becomes the default, and overriding it requires deliberate action (updating the ADR) rather than casual transgression.

7. The Control Quality Score: Continuous Governance Metrics

The Controllability Trap paper (Sahoo, ICLR 2026 Workshop on Agents in the Wild) introduces the Control Quality Score (CQS) — a composite real-time metric that reframes governance from binary (“is this system controlled?”) to continuous (“what is this system’s control quality right now, and is it sufficient?”) [4].

CQS drives a five-level graduated response protocol. When CQS drops below 0.4, available tools are programmatically restricted — a structural enforcement triggered by measured control degradation. While developed for military AI governance, the pattern maps directly to coding agent governance: a team could monitor CQS across agent sessions and automatically reduce tool access when quality signals degrade (test failures, review rejections, security violations).

This connects back to Teleport’s data: rather than static permission grants, organizations need dynamic permission management that responds to observed agent behavior. The CQS framework provides a conceptual model for how that dynamic governance could work.

8. Martin Fowler’s ADR Update: Inverted Pyramid for Machine Readability

Martin Fowler’s recent update to his ADR bliki entry emphasizes writing ADRs in “inverted pyramid” style — most important material first, details later [6]. While framed as general writing advice, this has specific implications for agent consumption: coding agents operating under context window constraints benefit from front-loaded decisions, where the architectural constraint appears in the first lines rather than buried after pages of rationale.

This aligns with the architecture.md pattern from the InfoQ article, where each ADR is reduced to a single directive line with severity level. The inverted pyramid is, in effect, the human-readable version of the machine-readable directive.

Practical Implications

Start with Layer 2, Not Layer 3

Most teams adopting coding agents start with AGENTS.md or CLAUDE.md files (Layer 3) because they are the easiest to create. This is backwards from a risk perspective. Start by ensuring your existing CI/CD pipeline catches architectural violations in agent-generated code the same way it catches them in human code. If you have ArchUnit tests, they already work. If you have OpenAPI linters, they already work. If you have nothing, adding Spectral for API governance or ArchUnit for dependency rules provides immediate value for both human and agent code.

Create an architecture.md with Enforcement Severities

Adopt the InfoQ article’s pattern of reducing each active ADR to a single directive with [Block] or [Warn] severity. Place this file at the repository root where both agents and CI tools can consume it. For [Block]-level rules, ensure corresponding automated checks exist in the pipeline. For [Warn]-level rules, rely on agent in-context compliance but track violation frequency.

Example starting template:

# Architecture Decisions (Machine-Readable)

## Data Ownership
* [ADR-001] [Block] Each service owns its database schema exclusively
* [ADR-002] [Block] Cross-service data access via published APIs only

## Communication
* [ADR-010] [Block] Async events via Kafka for inter-service communication
* [ADR-011] [Warn] REST for synchronous queries; gRPC for internal high-throughput

## Security
* [ADR-020] [Block] No static credentials in code or configuration
* [ADR-021] [Block] All secrets via vault with short-lived tokens

Evaluate Archgate for ADR-to-Rule Automation

The Archgate CLI is the first purpose-built tool for pairing ADRs with executable TypeScript rules. For teams maintaining ADRs, it provides a structured path from documentation to enforcement with CI integration and editor plugins for Claude Code and Cursor. The Apache-2.0 license and active release cadence (46 releases) make it worth evaluating, though the project’s youth warrants starting with non-critical rules.

Apply the ALARA Principle to Agent Tool Access

Audit every agent’s tool access and remove capabilities that are not required for its specific task. The ALARA paper’s insight is that this is not a one-time configuration but a design principle: each agent role should have a curated tool list that functions as both capability advertisement and permission boundary. If your agents have shell access, file system access, and network access when they only need to edit code in a specific directory, you are carrying unnecessary risk — exactly the pattern Teleport’s data shows leads to 4.5x more incidents.

Implement Graduated Response, Not Binary Permissions

The CQS framework suggests monitoring agent performance metrics (test pass rates, review approval rates, security scan results) and programmatically adjusting permissions in response. An agent that passes 95% of CI checks on first submission earns broader autonomy. An agent whose submissions consistently fail security scans gets restricted tool access. This requires instrumentation but transforms governance from a static configuration to a dynamic feedback loop.

Use ADRs to Create Agent Resistance to Architectural Drift

Store ADRs in the repository (not in Confluence or Notion) and reference them in your AGENTS.md or CLAUDE.md. The Copilot code review demonstration shows that agents with ADR access actively resist architectural violations — even when instructed to violate them. This creates a valuable “architectural immune system” where the documented intent exerts continuous pressure against drift.

Open Questions

  1. Scaling architecture.md. The InfoQ article’s atomic directive format works for dozens of ADRs. How does it scale to hundreds? Does the architecture.md file need hierarchical organization, domain-specific sharding, or dynamic loading based on change context?

  2. Conflict resolution between layers. What happens when an in-context instruction (Layer 3) contradicts a CI enforcement rule (Layer 2)? If architecture.md says [Warn] but the fitness function blocks, the agent wastes a generation cycle. If the prose says [Block] but no automated check exists, the constraint depends entirely on model compliance. How should teams manage consistency across layers?

  3. Agent-generated ADRs. If agents can read and enforce ADRs, can they also propose new ones when they detect emergent architectural patterns? The Archgate tool supports capturing “emerging architectural patterns back into ADRs,” but the governance implications of agent-authored architectural decisions are unexplored.

  4. Cross-repository governance. Most tooling assumes a single repository. Organizations with hundreds of services need cross-repository architectural governance — the platform team defines rules, every repository enforces them. The OpenAPI validator pattern addresses this for APIs, but broader architectural constraints (event schemas, shared libraries, deployment patterns) lack equivalent tooling.

  5. Measuring guardrail effectiveness. Teleport quantifies the cost of over-permissioning but no one has published data on the productivity cost of over-constraining. What is the optimal constraint level? How do teams measure whether their guardrails are preventing incidents without preventing innovation?

  6. Context window budget allocation. If agents can follow roughly 150-200 instructions reliably, and system prompts consume 50, how should teams allocate the remaining budget between coding standards, architectural constraints, security rules, and task-specific instructions? Is there a principled framework for prioritizing which constraints get in-context representation versus CI-only enforcement?

Sources

  1. Teleport, “2026 State of AI in Enterprise Infrastructure Security” — https://www.infoq.com/news/2026/03/teleport-ai-report/
  2. Adaptech Group et al., “Architectural Governance at AI Speed” (InfoQ) — https://www.infoq.com/articles/architectural-governance-ai-speed/
  3. Agostino & D’Souza, “ALARA for Agents: Least-Privilege Context Engineering Through Portable Composable Multi-Agent Teams” (arXiv 2603.20380) — https://arxiv.org/abs/2603.20380v1
  4. Sahoo, “The Controllability Trap: A Governance Framework for Military AI Agents” (ICLR 2026 Workshop) — https://arxiv.org/abs/2603.03515
  5. HumanLayer, “Writing a Good CLAUDE.md” — https://www.humanlayer.dev/blog/writing-a-good-claude-md
  6. Fowler, “Architecture Decision Record” (bliki, updated March 2026) — https://martinfowler.com/bliki/ArchitectureDecisionRecord.html
  7. Jovanovic, “Introducing AgentGuard — Declarative Guardrails for .NET AI Agents” — https://www.strathweb.com/2026/03/introducing-agentguard-declarative-guardrails-for-dotnet-ai-agents/
  8. Archgate CLI — https://github.com/archgate/cli
  9. Niessen, “Fitness Functions: Automating Your Architecture Decisions” — https://lukasniessen.medium.com/fitness-functions-automating-your-architecture-decisions-08b2fe4e5f34
  10. Hands-on Architects, “Protecting Architecture with Automated Tests in Python” — https://handsonarchitects.com/blog/2026/protecting-architecture-with-automated-tests-in-python/
  11. Lyu, “ADR in Code: Architecture Compliance with AI Code Reviews” — https://shinglyu.com/blog/2026/03/01/ai-adr-code-review.html
  12. Feroz, “AGENTS.md vs Architecture Decision Records” — https://ai.gopubby.com/agents-md-is-the-ew-architecture-decision-record-adr-3cfb6bdd6f2c
  13. Authority Partners, “AI Agent Guardrails: Production Guide for 2026” — https://authoritypartners.com/insights/ai-agent-guardrails-production-guide-for-2026/
  14. NPC-Worldwide, npcsh — https://github.com/NPC-Worldwide/npcsh
  15. AIMultiple, “Agents.md: A Machine-Readable Alternative to README” — https://research.aimultiple.com/agents-md/
  16. DeployHQ, “CLAUDE.md, AGENTS.md, and Every AI Config File Explained” — https://www.deployhq.com/blog/ai-coding-config-files-guide
  17. Bump.sh, “Leveraging the OpenAPI Specification for API Governance” — https://bump.sh/blog/leveraging-openapi-specification-api-governance/
  18. Ranthebuilder, “Serverless APIs: Auto-Generate OpenAPI Docs & CI/CD Protections” — https://www.ranthebuilder.cloud/post/openapi-ci-cd-automation
  19. joelparkerhenderson, “Architecture Decision Record Examples” — https://github.com/joelparkerhenderson/architecture-decision-record
  20. InfoQ, “New Research Reassesses the Value of AGENTS.md Files for AI Coding” — https://www.infoq.com/news/2026/03/agents-context-file-value-review/
  21. Anthropic, “Best Practices for Claude Code” — https://code.claude.com/docs/en/best-practices
  22. Osmani, “How to Write a Good Spec for AI Agents” — https://addyosmani.com/blog/good-spec/